Box

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 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 removes the mask as scrolling reveals them. 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 mask clips to the padding box. It preserves the Box border, shadows, and focus ring when no edge is hidden.

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 all fields changed since the last event; current is the full snapshot. Reporting pauses off screen and resumes with a fresh snapshot when Box returns.

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 first report has no added delay; subsequent reports include a trailing update with the latest values. Omit it or pass 0 for frame-based reporting. Negative or non-finite values use 0. The interval applies to onMeasureChange; context events are not throttled. Throttling limits event delivery; it does not reduce observer reads. edges, scroll, and fade continue measuring during scrolling so their CSS states remain current.

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

This readout observes ['size', 'overflow', 'edges', 'scroll'] with throttle={100}. Resize or scroll the Box to update it.

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

<Box
  round={8}
  className="measure-probe-box"
  observe={['size', 'overflow', 'edges', 'scroll']}
  throttle={100}
  onMeasureChange={(_, { current }) => setMeasurement(current)}
>
  <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
  <div className="measure-probe-wide">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]) => (
    <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; }

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; }