overflow-guard

Build around content, not breakpoints.

Visit the website

overflow-guard includes two packages:

React	HTML
overflow-guard-react	overflow-guard-html
React component and hook API for adaptive UI.	Framework-agnostic custom element for adaptive UI.
bun add overflow-guard-react	bun add overflow-guard-html
React docs · Package README	HTML docs · Package README

Why use it

• Build around content, not guessed pixel values
• Handle dynamic labels, localization, and data-driven content
• Reuse the same UI across narrow sidebars, wide panels, and resizable layouts
• Respond to horizontal overflow, vertical overflow, or both

AI usage

The recommended AI integration path is TanStack Intent.

• overflow-guard-react and overflow-guard-html ship their own package-local skills so the guidance can stay aligned with the installed library version.
• If you use a standalone skill installer ecosystem, you can still keep separate compatibility skills, but TanStack Intent is the canonical path for this repo.
• After installing a package, use npx @tanstack/intent@latest list to discover available skills in your project.

React docs

Full docs: packages/overflow-guard-react/README.md

overflow-guard-react helps React UI adapt when content stops fitting, instead of relying on viewport breakpoints, container breakpoints, or magic numbers.

Wrap a piece of UI in <OverflowGuard>, and it tells you when content no longer fits the available space. You can then switch to a compact layout, collapse actions to icons, swap a full nav for a menu, or reveal a "Read more" affordance.

Installation

bun add overflow-guard-react
npm install overflow-guard-react
pnpm add overflow-guard-react
yarn add overflow-guard-react

overflow-guard-react is a client-side package. It measures rendered DOM with ResizeObserver, so use it from client components in frameworks that distinguish server and client rendering.

Quick start

import { OverflowGuard } from "overflow-guard-react";

export function AdaptiveToolbar() {
  return (
    <OverflowGuard>
      {(isOverflowing) => (
        <div className={isOverflowing ? "toolbar toolbar--compact" : "toolbar"}>
          {isOverflowing ? (
            <>
              <button aria-label="Search">S</button>
              <button aria-label="Share update">U</button>
              <button aria-label="Launch flow">+</button>
            </>
          ) : (
            <>
              <button>Search</button>
              <button>Share update</button>
              <button>Launch flow</button>
            </>
          )}
        </div>
      )}
    </OverflowGuard>
  );
}

Runtime state

• isOverflowing: true when content overflows on any axis
• overflowAxis: 'none' | 'horizontal' | 'vertical' | 'both'

For fallback mode, render props, hooks, and more detailed examples, see packages/overflow-guard-react/README.md.

HTML docs

Full docs: packages/overflow-guard-html/README.md

overflow-guard-html is a framework-agnostic custom element that measures whether rendered content still fits its available space and applies reversible fallback mutations when it does not.

It keeps a hidden measurement copy of the original content, watches that copy for overflow, and only mutates the visible primary tree.

Installation

bun add overflow-guard-html
npm install overflow-guard-html
pnpm add overflow-guard-html
yarn add overflow-guard-html

CDN and raw HTML

For no-build pages, prototypes, embeds, or CMS usage, you can load the browser bundle directly from a CDN:

<script src="https://cdn.jsdelivr.net/npm/overflow-guard-html@0"></script>

If you prefer a module script instead, load the ESM file directly:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/overflow-guard-html@0/dist/index.js"
></script>

Quick start

<script src="https://cdn.jsdelivr.net/npm/overflow-guard-html@0"></script>

<style>
  .toolbar .icon-action {
    display: none;
  }

  .toolbar.toolbar--compact .full-action {
    display: none;
  }

  .toolbar.toolbar--compact .icon-action {
    display: inline-flex;
  }
</style>

<overflow-guard fallbackClass="toolbar--compact">
  <nav class="toolbar">
    <span>Sprint planning</span>
    <div>
      <button class="full-action">Search documents</button>
      <button class="icon-action" aria-label="Search">S</button>
      <button class="full-action">Share update</button>
      <button class="icon-action" aria-label="Share">U</button>
      <button class="full-action">Launch flow</button>
      <button class="icon-action" aria-label="Launch">+</button>
    </div>
  </nav>
</overflow-guard>

Runtime state

• overflowing: present when overflow is active on any axis
• overflow-axis: none | horizontal | vertical | both
• data-overflow-axis: same value as overflow-axis

For attributes, events, methods, and usage notes, see packages/overflow-guard-html/README.md.