Box ✦Documentation has not yet been reviewed by a human.

Box is a DOM container with layout props, overflow states, and browser context events. For custom wheel, pointer, and touch handling, use Capture.

Display

Use display, gap, padding, margin, and round for layout and corners. Numeric lengths use pixels; strings accept CSS lengths. padding and margin also accept CSS shorthand, such as padding="8px 16px" or margin="0 auto". Omission adds no spacing styles. A bare round fully rounds the corners.

Box uses position: relative by default. Absolutely positioned descendants use it as their containing block. Set position: static on the Box if they should use another positioned ancestor.

<Box round={8} padding={10}><span /></Box>
<Box display="flex" round={8} gap={6} padding={10}><span /></Box>
<Box display="grid" round={8} gap="0.5rem" padding="8px 16px" style={{ gridTemplateColumns: '1fr 1fr' }}><span /></Box>

Overflow

Box reports overflow, clipping, and scrollability as measurements and CSS states. Use observe="overflow" to keep overflow, clipping, and scrollability states current as content changes. observe="edges" also tracks which edges hide content while scrolling. fade enables both automatically.

.edge is a demo class name. Use your own selector.

<Box observe="overflow" round={8} className="edge" style={{ width: 150 }}>Content that fits.</Box>

<Box observe="overflow" round={8} className="edge" style={{ width: 150, overflow: 'hidden', whiteSpace: 'nowrap' }}>
  A label too long for this box.
</Box>

<Box observe="overflow" round={8} className="edge" style={{ width: 150, height: 56, overflowY: 'auto' }}>
  One. Two. Three. Four. Five. Six. Seven. Eight. Nine. Ten.
</Box>

.edge:state(clipped-x) { border-color: var(--border-3-warning); }
.edge:state(scrollable-y) { border-color: var(--border-3-info); }

Fading a clipped edge

fade masks edges with hidden content and eases the mask as scrolling reveals them. The mask is removed after the last edge fades out, preserving shadows and focus rings at rest. fadeSize sets its depth. It measures on connection, even off screen.

const TAGS = ['frontend', 'design-system', 'a11y', 'performance']

<Box fade fadeSize={32} round display="flex" gap={6} className="fade-demo" style={{ width: 190, overflowX: 'auto' }}>
  {TAGS.map((t) => <Tag key={t} size="small" label={t} />)}
</Box>

<Box fade fadeSize={32} round={8} className="fade-demo" style={{ width: 190, height: 56, overflowY: 'auto' }}>
  One. Two. Three. Four. Five. Six. Seven. Eight. Nine. Ten. Eleven. Twelve.
</Box>

.fade-demo { flex-wrap: nowrap; padding: 10px; border: 1px solid var(--border-4); }
.fade-demo a-tag { flex: 0 0 auto; }

The fade affects the padding box. The mask remains through its exit transition, then disappears so shadows and focus rings are visible at rest. The easing is disabled when reduced motion is requested.

To style hidden edges without fade, use observe="edges" and the hidden-start-x, hidden-end-x, hidden-start-y, or hidden-end-y CSS states.

Tooltip on clipped content

Tooltip truncatedOnly shows when Box clips content on either axis, including wrapped children.

const TAGS = ['frontend', 'design-system', 'a11y', 'performance']

<Box display="flex" round={8} gap={6} className="tag-box" style={{ height: 34 }}>
  {TAGS.map((t) => <Tag key={t} size="small" label={t} />)}
  <Tooltip truncatedOnly>{TAGS.join(' · ')}</Tooltip>
</Box>

.tag-box { flex-wrap: wrap; padding: 6px; overflow: hidden; }

Measurements

By default, onMeasureChange reports one frame after observation starts, then when the border-box width or height changes. changed contains fields changed since the last event; current is the full snapshot. Reporting pauses off screen and resumes with a fresh snapshot when Box returns.

Pass observeOffscreen when a virtualized layout needs measurement events or clipping states while the Box is outside the viewport. It keeps the selected observers active. Use throttle to limit reads when offscreen content changes often.

observe accepts one of the eight selections below, or a typed array combining them. observe={['size', 'edges']} and observe={['edges', 'size']} select the same triggers. Repeated selections have no effect. Changing the selected measurement fields requests a fresh snapshot. TypeScript checks each value; use an array to combine selections in JSX.

The selections below progress from resize and context signals to continuous scroll tracking. Intensity describes typical observation work and event frequency, not a fixed performance rating. Content churn and the work in your handler also affect the cost.

Selections are independent. scroll selects offset triggers; it does not include size, overflow, edges, or context. Every measurement event still contains fresh values for every measurement field, including client/content dimensions and hidden edges. Combine triggers when you also need events caused by those other changes. With observe="size", content-only changes cause no event; the next size event includes the current content measurements.

For a scroll-edge indicator, use edges: it reads during scrolling but avoids a callback for each offset change. scroll and all can cause the most frequent application updates, especially when the handler sets state or sends each snapshot to a worker. Prefer fade when CSS alone needs the edge state.

When no measurement is selected, onMeasureChange adds size; onContextChange adds context. Passing both handlers observes size and context without enabling scroll events. Without handlers or fade, omitting observe keeps Box idle.

Set throttle to a minimum interval in milliseconds. The initial measurement is immediate; later activity gets a trailing read with the latest values. Omit it or pass 0 for frame-based updates. Negative or non-finite values use 0. The interval limits measurement reads, CSS state updates, and onMeasureChange events; context events are not throttled. The box.measurement getter still reads fresh values on demand.

Tooltip truncatedOnly reads Box’s clipping on demand. It works without observe or onMeasureChange and does not enable continuous observation.

Pass includeRectsFor to add matching descendants to each measurement snapshot. current.rects contains their border boxes in document order, with top, left, right, and bottom measured from the Box’s top-left border edge, plus each match’s width and height.

The selector does not start observation or add event triggers. Box reads the rects when an existing observe selection reports a change. current.rects always contains the latest array; changed.rects appears only when that array differs from the previous report. For a fresh read at any time, use box.measurement.rects.

With observe="scroll" and no throttle, Box can query, measure, and compare every matching descendant on each reported frame. Keep the selector focused or set throttle when many descendants match. A larger interval also delays the fade as the reader reaches an edge.

This readout observes ['size', 'overflow', 'edges', 'scroll'] with throttle={100} and fade. It includes the first content row in rects. Resize or scroll the Box to update the values and edge mask.

const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)

<Box
  round={8}
  className="measure-probe-box"
  observe={['size', 'overflow', 'edges', 'scroll']}
  fade
  includeRectsFor=".measure-probe-target"
  throttle={100}
  onMeasureChange={(_, { current }) => setMeasurement(current)}
>
  <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
  <div className="measure-probe-wide measure-probe-target">wide content, so both axes overflow</div>
  <div className="measure-probe-wide">and a second line, so the vertical axis does too</div>
  <div className="measure-probe-wide">and a third</div>
</Box>

<div className="measure-probe-readout">
  {Object.entries(measurement ?? {}).map(([field, value]) => field === 'rects' && Array.isArray(value)
    ? <div key={field} className="measure-probe-rects">
        <Tag size="small" label="rects" value={`${value.length} match${value.length === 1 ? '' : 'es'}`} />
        <pre><code>{JSON.stringify(value, null, 2)}</code></pre>
      </div>
    : <Tag key={field} size="small" label={field} value={String(value)} />
  )}
</div>

.measure-probe-box {
  resize: both;
  overflow: auto;
  inline-size: 320px;
  block-size: 132px;
  min-inline-size: 120px;
  min-block-size: 64px;
  padding: 10px;
  border: 1px solid var(--border-4);
}
.measure-probe-wide { inline-size: 520px; padding-block: 6px; }
.measure-probe-readout { display: flex; flex-wrap: wrap; gap: 6px; }
.measure-probe-rects { flex-basis: 100%; min-width: 0; }
.measure-probe-rects pre { margin: 4px 0 0; padding: 8px; border: 1px solid var(--border-4); border-radius: 4px; background: var(--bg-2); white-space: pre-wrap; overflow-wrap: anywhere; }

See the measurement fields. Overflow fields map to kebab-case CSS states, such as clippedX → :state(clipped-x).

Context

onContextChange reports theme, focus, and browser context as { changed, current }. See the context fields. For CSS, use :focus-within, mode classes, and media queries instead.

Switch themes, resize, or zoom to update the preview. The .light Box keeps its local mode; globalMode follows the document. Browser and OS versions may be frozen, so use pointer, hover, or feature tests to choose behavior.

import { useState } from 'react'
import { Box, Tag, Text, type BoxContext } from '@antadesign/anta'

function ScopedContext() {
  const [context, setContext] = useState<BoxContext | null>(null)

  return (
    <div className="light">
      <Box display="flex" round={8} gap={6} className="context-probe-box"
           onContextChange={(_, { current }) => setContext(current)}>
        <Text size="small" priority="tertiary">inside a .light scope</Text>
        <Tag size="small" tone="brand" label="mode" value={context?.mode ?? '…'} />
        <Tag size="small" label="globalMode" value={context?.globalMode ?? '…'} />
      </Box>
    </div>
  )
}

.context-probe-box {
  flex-wrap: wrap;
  align-items: center;
  padding: 10px;
  border: 1px solid var(--border-4);
  background: var(--bg-1);
  color: var(--text-1);
}

const canvasRef = useRef<HTMLCanvasElement>(null)

<Box className="canvas-probe"
  onContextChange={(_, { current }) => {
    const canvas = canvasRef.current
    const ctx = canvas?.getContext('2d')
    if (!canvas || !ctx) return

    const { font, devicePixelRatio: dpr } = current
    canvas.width = canvas.clientWidth * dpr
    canvas.height = canvas.clientHeight * dpr
    ctx.scale(dpr, dpr)

    ctx.font = font.shorthand
    ctx.letterSpacing = font.letterSpacing
    ctx.wordSpacing = font.wordSpacing
    ctx.direction = font.direction === 'rtl' ? 'rtl' : 'ltr'
    ctx.fillStyle = font.color

    ctx.fillText('Matches the DOM', 0, font.lineHeight ?? font.size)
  }}
>
  <span>Matches the DOM</span>
  <canvas ref={canvasRef} aria-label="Canvas text using the Box font and color" />
</Box>

.canvas-probe { width: 100%; font-size: 20px; line-height: 32px; color: var(--text-1); }
.canvas-probe canvas { display: block; width: 100%; height: 48px; }

<a-box display="grid" gap="8px" round="12px" observe="all"
       style="--box-gap: 8px; --box-round: 12px; padding: 12px; border: 1px solid var(--border-4)">
  <span>Summary content</span>
  <span>Observation enabled</span>
</a-box>

<a-box display="flex" gap padding margin round fade class="raw-box"
       style="--box-gap: 8px; --box-padding: 12px; --box-margin: 0 auto; --box-round: 12px; --box-fade-size: 32px">
  <span>Layout</span><span>Context</span><span>Measurements</span>
</a-box>

.raw-box { width: 190px; overflow: auto; border: 1px solid var(--border-4); }
.raw-box span { flex: 0 0 auto; }