Skip to content

Resizable

Resize handle and the headless useResizable engine behind the resizable prop on Box, Flex, Card and Sidebar. The element owns its own size; for panes that trade space with neighbours use PanelGroup from @shavin/ui/panels.

// Plain markup
import { ResizeHandle, ResizeHandles } from "@shavin/ui";

Inspector resized from its left edge

The canvas is flex-1, so it gives up the space the inspector takes. Drag the border, or focus it with Tab and use the arrow keys.

Canvas

Inspector

Component Source
<Flex className="h-72">
  <Box className="flex-1 p-4">Canvas</Box>
  <Box
    resizable="left"
    minWidth={200}
    maxWidth={420}
    persistKey="docs-inspector"
    className="w-64 border-l border-hairline bg-surface p-4"
  >
    Inspector
  </Box>
</Flex>

Bottom panel resized from its top edge

Editor

Terminal

Component Source
<Flex direction="column" gap="0" className="h-80">
  <Box className="flex-1 p-4">Editor</Box>
  <Box resizable="top" minHeight={80} maxHeight={240} className="h-32 border-t border-hairline bg-surface p-4">
    Terminal
  </Box>
</Flex>

Card with a grip

resizable="both" adds the right edge, the bottom edge and the bottom-right corner. While you drag, the grip slides along the edge with the pointer and the size shows; on release it glides back to the centre.

Notes

Drag the corner or either edge.

Component Source
<Card resizable="both" resizeHandle="grip" minWidth={200} maxWidth={480} minHeight={120} maxHeight={280} padding="md" className="w-72 h-40">
  <Flex direction="column" gap="3">
    <Text weight="medium">Notes</Text>
    <Text size="sm" color="subtle">Drag the corner or either edge.</Text>
  </Flex>
</Card>

Handle colours

resizeColor sets the hover, focus and drag colour: brand-subtle (default, a softer brand), brand, or neutral for monochrome interfaces. Lines stop where the rounded corners begin, and corner handles sit on the curve.

brand

Hover an edge.

brand-subtle

Hover an edge.

neutral

Hover an edge.

Component Source
<Card resizable="both" resizeColor="brand" padding="md" className="w-56 h-32">…</Card>
<Card resizable="both" resizeColor="brand-subtle" padding="md" className="w-56 h-32">…</Card>
<Card resizable="both" resizeColor="neutral" padding="md" className="w-56 h-32">…</Card>

Headless hook

useResizable owns the size and the keyboard and pointer handling; ResizeHandles draws the Shavin handles. Spread getHandleProps(edge) onto your own elements for a custom look.

Custom element, both side edges

Component Source
const r = useResizable({ edges: "x", minWidth: 160, maxWidth: 480 });

<Box ref={r.ref} style={r.style} className="relative w-64 ...">
  …
  <ResizeHandles state={r} />
</Box>

Keyboard

Every handle is a focusable separator. Arrow keys move the focused edge by resizeStep (16px by default) and Shift moves 4 times as far. Home and End jump to the minimum and maximum. Enter or a double-click resets the natural size and clears persistKey.

Box, Flex or PanelGroup?

The resizable prop is for one element that owns its size and resizes against flexible space. When two or more panes have to share a fixed space, use PanelGroup from @shavin/ui/panels.

Props

PropTypeDefaultDescription
bgVideostring—Background video URL (mp4, webm, etc.). Renders an autoPlay/loop/muted <video> element behind children.
bgImagestring—Background image URL. Renders an <img> with object-cover (default) or object-contain.
bgSize"cover" | "contain"coverBackground media fit. "cover" fills the container (default), "contain" fits within.
bgOverlaysstring—Comma-separated shorthand for overlay layers. Supports presets ("dark-50"), solid colors (#hex or (token)), gradients (linear/radial), and fx backdrops ("fx:dither-waves", "fx:fluid-silk(speed=1.2)"; needs @shavin/fx registered, else falls back to mesh). JSON array of OverlayLayer[] as fallback for advanced cases. Layers composite top-to-bottom.
bgVideoPausedbooleanfalseWhen true, pauses the background video (renders a static poster frame instead of autoplay).
resizableResizableEdges—Make the element user-resizable from these edges: "right", "bottom", "x", "y", "both", true, or a list such as ["left", "bottom-left"]. Off by default.
minWidthnumber—Minimum width in px while resizable (also applied as CSS min-width).
maxWidthnumber—Maximum width in px while resizable (also applied as CSS max-width).
minHeightnumber—Minimum height in px while resizable (also applied as CSS min-height).
maxHeightnumber—Maximum height in px while resizable (also applied as CSS max-height).
resizeStepnumber16Arrow-key resize step in px; Shift multiplies by 4. Default 16.
snapnumber—Round dragged sizes to this grid in px.
lockAspectRatioboolean—Keep the width/height ratio while resizing.
persistKeystring—Remember the size in localStorage under this key.
onResize(size: ResizeSize) => void—Fires once per frame while resizing.
onResizeEnd(size: ResizeSize) => void—Fires when a resize finishes.
resizeHandleResizeHandleVariantlineHandle look: "line" (brand line on hover), "grip" (always-visible pill) or "invisible". Default "line".
resizeColorResizeHandleColorbrand-subtleHandle colour on hover, focus and drag: "brand", "brand-subtle" (softer brand) or "neutral" (monochrome). Default "brand-subtle".
asElementTypedivPolymorphic element tag: div, section, article, span, etc. Default "div".
translucentboolean—Whether to apply translucent panel styling with data-panel attribute.
surfaceSurface—Surface contrast scope intent. "dark"/"light" auto-invert against the page theme (contrast band). "dark-always"/"light-always" lock to one theme regardless of page (for media backgrounds). Undefined inherits page theme.
refRef<HTMLElement>—Ref to the rendered element.
Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font