npx skills add arturmarc/overflow-guard --skill overflow-guard-reactOverflowGuard React
Use this skill when a React UI should respond to actual content overflow instead of viewport breakpoints or fixed container query thresholds.
Reach for it when
- a user asks to make a React component "responsive" and the real constraint is content fit
- labels, translations, optional actions, or data-driven counts make a row stop fitting
- a toolbar should collapse from full buttons to icons
- a full navigation should swap to a compact menu only when links overflow
- fixed-height content should react to vertical overflow
Do not reach for it first when:
- plain CSS wrapping solves the problem cleanly
- the UI should change at a product-defined breakpoint regardless of content
- the component is not in React
Public API
Import from overflow-guard-react:
import { OverflowGuard, useOverflowGuard } from 'overflow-guard-react'
OverflowGuard has two exclusive modes.
Fallback mode
Use this when the compact state is a separate tree.
<OverflowGuard fallback={<CompactToolbar />} fallbackOn="horizontal">
<FullToolbar />
</OverflowGuard>
Rules:
fallbackis required in this modefallbackOnsupportshorizontal,vertical, orboth- the default
fallbackOnisboth
Render-prop mode
Use this when the same tree should rearrange itself based on overflow state.
<OverflowGuard>
{(isOverflowing, overflowAxis) => (
<div className={isOverflowing ? 'flex flex-col gap-3' : 'flex items-center gap-3'}>
...
</div>
)}
</OverflowGuard>
Rules:
- children is a function with the shape
(isOverflowing, overflowAxis) => ReactNode overflowAxisis one ofnone,horizontal,vertical, orboth- do not pass
fallbackorfallbackOnin this mode
Hook usage
Use useOverflowGuard() only inside descendants of the visible OverflowGuard tree when a nested child only needs the boolean state.
function ToolbarSummary() {
const isOverflowing = useOverflowGuard()
return <span>{isOverflowing ? 'compact' : 'expanded'}</span>
}
The hook returns only a boolean, not the axis.
Preferred patterns
Prefer render-prop mode when:
- the same component can switch layout classes
- you are swapping text buttons for icons
- you need axis-aware behavior
- you want to keep one component tree and preserve local state
Prefer fallback mode when:
- the compact view is meaningfully different markup
- accessibility or semantics are clearer with a separate tree
- the compact version is a menu, sheet trigger, or alternate navigation shell
Constraints and gotchas
- fallback mode and render-prop mode are mutually exclusive
fallbackOnis only valid whenfallbackis present- if behavior differs by axis, check
overflowAxisexplicitly - preserve accessible names when collapsing text buttons into icon buttons
- this package measures rendered DOM with
ResizeObserver, so treat it as client-side behavior
Workflow
- Identify where content can outgrow its space.
- Check whether the real requirement is content-aware responsiveness rather than breakpoint-driven behavior.
- Decide whether the compact state is a separate tree or the same tree rearranged.
- Wrap the affected area in
OverflowGuard. - Implement the compact or expanded behavior.
- If only descendants need state, consume
useOverflowGuard(). - Verify with narrow widths, long labels, translated strings, dynamic item counts, and fixed-height cases.