Box

New

Primitive container for surface, border, spacing, sizing, and positioning.

Usage

DtBox complements DtText (typography) and DtStack (flex layout) to form Dialtone's primitive triad:

  • DtBox: what the container is (surface, border, padding, sizing, positioning)
  • DtText: what the content looks like (font, size, color)
  • DtStack: how children are arranged (direction, gap, alignment)

Guidance

  • Use DtBox in place of composing multiple surface utility classes (e.g., d-bgc-*, d-bc-*, d-bar*, d-bs-*, d-p-*, d-ps-*).
  • Use the as prop to render semantic HTML elements (section, nav, article, header, etc.) for accessibility.
  • DtBox is a passive container — it does not arrange children (use DtStack) or handle typography (use DtText).
  • Compose DtBox + DtStack + DtText together for structured UI surface containers.

Do

  • Use DtBox for card surfaces, info panels, content regions, and any container that needs surface styling.
  • Use DtBox for common token-backed container positioning such as sticky headers, relative anchors, and logical insets.
  • Compose with DtStack for layout: <dt-box><dt-stack>...</dt-stack></dt-box>.
  • Use the as prop for semantic HTML: <dt-box as="nav">, <dt-box as="section">.
  • Use class for one-off styling outside DtBox's prop surface, including responsive, calc, reset, arbitrary, or non-DtBox positioning utilities.

Don’t

  • Don't use DtBox for flex layout — use DtStack for direction, gap, alignment.
  • Don't use DtBox for typography — use DtText for font, size, tone.
  • Don't use utility classes for properties DtBox already handles (e.g., avoid class="d-bgc-primary" when surface="primary" exists).
  • Don't use DtBox positioning props as a replacement for overlay components, teleports, dialogs, or popovers.
  • Don't nest DtBox deeply when a dedicated component (DtCard, DtNotice) better fits the pattern.

Surface

Background surface color mapped to --dt-color-surface-* tokens.

Semantic surfaces

Padding

Spacing token scale values for internal whitespace. The padding cascade resolves specific sides over axis shorthands over the all-sides shorthand.

Directional padding

Override specific sides. The cascade resolves: paddingBlockStart > paddingBlock > padding.

Border

Border width

No visible border until a border-width is set. Uniform width applies to all sides.

Directional border width

Show borders on specific sides only.

Border color

Defaults to 'default' (--dt-color-border-default). Only visible when a border-width is set.

Border radius

Shadow

Sizing

Maps to Dialtone's layout token scale (--dt-layout-*). Supports both fixed values and percentage tokens.

Positioning

Use position prop paired with inset and z-index props to position a box. The position prop maps to CSS's position property, and the inset props map to CSS's logical inset-* properties.

Their values map to Dialtone's coordinate value set: spacing values, negative spacing values, and percentage coordinates. For example, inset-block-start maps to the block-start edge, aka the physical value top.

As a fallback, positioning CSS utilities are available: position, coordinates, and z-index.

Logical insets

The inset cascade resolves specific sides over axis shorthands over the all-sides shorthand. inset positions the outside edges of a positioned box; use padding for internal spacing. Percentage coordinate values apply only to side-specific props.

Z-index

The z-index prop maps to Dialtone's semantic z-index tokens. Stacking order depends on the element's layout context, so prefer the lowest layer that fits the container and keep overlay behavior in dedicated overlay components.

Overflow

Scrollbar

Integrates the v-dt-scrollbar directive. An inner viewport wrapper is inserted automatically, solving the Custom Scrollbar's single-child constraint.

Render as

Use the as prop to render semantic HTML elements for accessibility.

Examples

Card

Composed layout

Accessibility

  • Use the as prop to render appropriate semantic elements — nav for navigation, section for thematic content, article for self-contained content.
  • DtBox does not add any implicit ARIA role. The rendered element's native semantics determine how screen readers interpret it.
  • When using as="nav" or as="section", consider adding aria-label to provide an accessible name for the landmark region.
  • The scrollbar integration preserves native keyboard scrolling behavior.

Vue API

import { DtBox } from '@dialpad/dialtone-vue';

Slots

Name
Type
default

Slot for main content

Props

Name
Default
Type
as
'div'
"div" | "span" | "section" | "article" | "aside" | "main" | "header" | "footer" | "nav" | "ul" | "ol" | "li" | "fieldset" | "form" | "figure"

HTML element to render as.

blockSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Block size (aka height). Maps to --dt-layout-* tokens.

borderColor
'default'
"transparent" | "subtle" | "default" | "moderate" | "bold" | "accent" | "positive" | "positive-subtle" | "positive-strong" | "warning" | "warning-subtle" | "warning-strong" | "critical" | "critical-subtle" | "critical-strong" | "info" | "info-subtle" | "info-strong" | "focus" | "brand" | "brand-subtle" | "brand-strong"

Border color. Maps to --dt-color-border-* tokens. Defaults to 'default'. Visible when any border-width prop is set.

borderRadius
"0" | "100" | "200" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "pill" | "circle"

Border radius. Maps to --dt-size-radius-* tokens.

borderWidth
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on all sides. Maps to --dt-size-border-* tokens.

borderWidthBlock
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the block axis (aka top/bottom). Overrides borderWidth for block sides.

borderWidthBlockEnd
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the block-end side (aka bottom). Overrides borderWidthBlock and borderWidth for block-end.

borderWidthBlockStart
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the block-start side (aka top). Overrides borderWidthBlock and borderWidth for block-start.

borderWidthInline
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the inline axis (aka left/right). Overrides borderWidth for inline sides.

borderWidthInlineEnd
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the inline-end side (aka right). Overrides borderWidthInline and borderWidth for inline-end.

borderWidthInlineStart
"0" | "50" | "100" | "150" | "200" | "300" | "400"

Border width on the inline-start side (aka left). Overrides borderWidthInline and borderWidth for inline-start.

inlineSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Inline size (aka width). Maps to --dt-layout-* tokens.

inset
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800"

Inset on all sides. Accepts spacing coordinate values and negative spacing coordinate values.

insetBlock
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800"

Inset on the block axis (aka top/bottom). Overrides inset for the block axis.

insetBlockEnd
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800" | "50p" | "100p" | "n50p" | "n100p"

Inset on the block-end side (aka bottom). Overrides insetBlock and inset for block-end. Also supports documented percentage coordinates.

insetBlockStart
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800" | "50p" | "100p" | "n50p" | "n100p"

Inset on the block-start side (aka top). Overrides insetBlock and inset for block-start. Also supports documented percentage coordinates.

insetInline
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800"

Inset on the inline axis (aka left/right). Overrides inset for the inline axis.

insetInlineEnd
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800" | "50p" | "100p" | "n50p" | "n100p"

Inset on the inline-end side (aka right). Overrides insetInline and inset for inline-end. Also supports documented percentage coordinates.

insetInlineStart
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800" | "n1" | "n25" | "n50" | "n75" | "n100" | "n125" | "n150" | "n175" | "n200" | "n250" | "n300" | "n350" | "n400" | "n450" | "n500" | "n525" | "n550" | "n600" | "n650" | "n700" | "n750" | "n800" | "50p" | "100p" | "n50p" | "n100p"

Inset on the inline-start side (aka left). Overrides insetInline and inset for inline-start. Also supports documented percentage coordinates.

maxBlockSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Maximum block size. Maps to --dt-layout-* tokens.

maxInlineSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Maximum inline size. Maps to --dt-layout-* tokens.

minBlockSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Minimum block size. Maps to --dt-layout-* tokens.

minInlineSize
"0" | "1px" | "2px" | "8px" | "25" | "20px" | "24px" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950" | "1000" | "1050" | "1100" | "1150" | "1200" | "1250" | "1300" | "1350" | "1400" | "1450" | "1500" | "1550" | "1600" | "10p" | "20p" | "25p" | "30p" | "33p" | "40p" | "50p" | "60p" | "66p" | "70p" | "75p" | "80p" | "90p" | "95p" | "100p"

Minimum inline size. Maps to --dt-layout-* tokens.

overflow
"hidden" | "scroll" | "auto" | "clip" | "visible"

Overflow behavior.

padding
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on all sides. Accepts spacing token scale values.

paddingBlock
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the block axis (aka top/bottom). Overrides padding for the block axis.

paddingBlockEnd
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the block-end side (aka bottom). Overrides paddingBlock and padding for block-end.

paddingBlockStart
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the block-start side (aka top). Overrides paddingBlock and padding for block-start.

paddingInline
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the inline axis (aka left/right). Overrides padding for the inline axis.

paddingInlineEnd
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the inline-end side (aka right). Overrides paddingInline and padding for inline-end.

paddingInlineStart
"0" | "1" | "25" | "50" | "75" | "100" | "125" | "150" | "175" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "525" | "550" | "600" | "650" | "700" | "750" | "800"

Padding on the inline-start side (aka left). Overrides paddingInline and padding for inline-start.

position
"static" | "relative" | "absolute" | "fixed" | "sticky"

CSS position value.

scrollbar
"leave" | "scroll" | "move" | "always"

Custom scrollbar via OverlayScrollbars. When set, an inner viewport wrapper (.d-box__scrollbar-content) is inserted automatically.

scrollbarContentClass
''
string|object|array

Additional CSS classes applied to the scrollbar content wrapper element. Only applies when scrollbar prop is set.

shadow
"small" | "medium" | "large" | "extra-large" | "card"

Box shadow. Maps to --dt-shadow-* tokens.

surface
"primary" | "primary-opaque" | "secondary" | "secondary-opaque" | "moderate" | "moderate-opaque" | "bold" | "bold-opaque" | "strong" | "strong-opaque" | "contrast" | "contrast-opaque" | "backdrop" | "overlay" | "brand" | "brand-opaque" | "brand-subtle" | "brand-subtle-opaque" | "brand-strong" | "info" | "info-opaque" | "info-subtle" | "info-subtle-opaque" | "info-strong" | "positive" | "positive-opaque" | "positive-subtle" | "positive-subtle-opaque" | "positive-strong" | "warning" | "warning-opaque" | "warning-subtle" | "warning-subtle-opaque" | "warning-strong" | "critical" | "critical-opaque" | "critical-subtle" | "critical-subtle-opaque" | "critical-strong"

Background surface color. Maps to --dt-color-surface-* tokens.

zIndex
"hide" | "base" | "base1" | "selected" | "active" | "navigation" | "navigation-fixed" | "dropdown" | "popover" | "tooltip" | "drawer" | "modal" | "modal-element" | "notification"

Z-index layer. Maps to --zi-* tokens.

Classes

Class
Applies to
Description

Box documentation last updated Friday, September 4, 2026

fix/popover-modal-zindex-scope