Skip to main content

Box

The box component provides a generic, flexible container for custom designs and layouts. Use box to apply styling like backgrounds, padding, borders, or border radius when existing components don't meet your needs, or to nest and group other components.

Box contents maintain their natural size, making it especially useful within layout components that would otherwise stretch their children. For structured layouts, use stack or grid.

Box doesn't provide built-in spacing between siblings or its own flex or grid layout. For controlled gaps between children, use stack or grid. For scrollable containers, use scroll box.

Support
Targets (29)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the box component.

Anchor to accessibilityLabel
accessibilityLabel
string

A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.

Anchor to accessibilityRole
accessibilityRole
Default: 'generic'

The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page.

Anchor to accessibilityVisibility
accessibilityVisibility
'visible' | 'hidden' | 'exclusive'
Default: 'visible'

Controls how the element is exposed to sighted users and to assistive technologies such as screen readers.

  • visible: The element is visible to all users (both sighted users and screen readers).
  • hidden: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information.
  • exclusive: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context.
Anchor to background
background
'base' | 'subdued' | 'transparent'
Default: 'transparent'

The background color of the box.

  • base: The standard background color for general content areas.
  • subdued: A muted background for secondary or supporting content.
  • transparent: No background color (the default).
Anchor to blockSize
blockSize
<>
Default: 'auto'

The block size of the element (height in horizontal writing modes). Learn more about the block-size property.

  • SizeUnits: Specific size values in pixels, percentages, or zero for precise control.
  • auto: Automatically sizes based on content and layout constraints.
Anchor to border
border
Default: 'none'

A shorthand for setting the border width, color, and style in a single property. Individual border properties (borderWidth, borderStyle) can override values set here.

Anchor to borderRadius
borderRadius
<Extract<$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>
Default: 'none'

The roundedness of the box's corners.

  • none: Sharp corners with no rounding.
  • small-100 / small: Subtle rounding for compact elements.
  • base: Standard rounding for most use cases.
  • large / large-100: More pronounced rounding for prominent containers.
  • max: Maximum rounding, creating a pill or circular shape.

Supports 1-to-4-value shorthand syntax for specifying different radii per corner.

Anchor to borderStyle
borderStyle
<> | ""
Default: '' - meaning no override

Controls the visual style of the border on all sides, such as solid, dashed, or dotted.

When set, this overrides the style value specified in the border property.

Supports 1-to-4-value syntax for specifying different styles per side:

  • One value: applies to all sides
  • Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
  • Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
  • Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
Anchor to borderWidth
borderWidth
<> | ''
Default: '' - meaning no override

The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by border.

Anchor to display
display
<"auto" | "none">
Default: 'auto'

Sets the outer display type of the component. The outer type sets a component’s participation in flow layout.

  • auto: The component’s initial value. The actual value depends on the component and context.
  • none: Hides the component from display and removes it from the accessibility tree, making it invisible to screen readers.

Learn more about the display property.

Anchor to id
id
string

A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.

Anchor to inlineSize
inlineSize
<>
Default: 'auto'

The inline size of the element (width in horizontal writing modes). Learn more about the inline-size property.

  • SizeUnits: Specific size values in pixels, percentages, or zero for precise control.
  • auto: Automatically sizes based on content and layout constraints.
Anchor to maxBlockSize
maxBlockSize
<>
Default: 'none'

The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the max-block-size property.

Anchor to maxInlineSize
maxInlineSize
<>
Default: 'none'

The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the max-inline-size property.

Anchor to minBlockSize
minBlockSize
<>
Default: '0'

The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the min-block-size property.

Anchor to minInlineSize
minInlineSize
<>
Default: '0'

The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the min-inline-size property.

Anchor to overflow
overflow
'hidden' | 'visible'
Default: 'visible'

The overflow behavior of the element.

  • visible: Content that extends beyond the container is visible.
  • hidden: Content that extends beyond the container is clipped and not scrollable.
Anchor to padding
padding
<<>>
Default: 'none'

The padding applied to all edges of the component.

Supports 1-to-4-value syntax using flow-relative values:

  • 1 value applies to all sides
  • 2 values apply to block (top/bottom) and inline (left/right)
  • 3 values apply to block-start (top), inline (left/right), and block-end (bottom)
  • 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left)

Examples: base, large none, base large-100 base small

Use auto to inherit padding from the nearest container with removed padding.

Anchor to paddingBlock
paddingBlock
<<> | "">
Default: '' - meaning no override

The block-direction padding (top and bottom in horizontal writing modes).

Accepts a single value for both sides or two space-separated values for block-start and block-end.

Example: large none applies large to the top and none to the bottom.

Overrides the block value from padding.

Anchor to paddingBlockEnd
paddingBlockEnd
< | "">
Default: '' - meaning no override

The block-end padding (bottom in horizontal writing modes).

Overrides the block-end value from paddingBlock.

Anchor to paddingBlockStart
paddingBlockStart
< | "">
Default: '' - meaning no override

The block-start padding (top in horizontal writing modes).

Overrides the block-start value from paddingBlock.

Anchor to paddingInline
paddingInline
<<> | "">
Default: '' - meaning no override

The inline-direction padding (left and right in horizontal writing modes).

Accepts a single value for both sides or two space-separated values for inline-start and inline-end.

Example: large none applies large to the left and none to the right.

Overrides the inline value from padding.

Anchor to paddingInlineEnd
paddingInlineEnd
< | "">
Default: '' - meaning no override

The inline-end padding (right in LTR writing modes, left in RTL).

Overrides the inline-end value from paddingInline.

Anchor to paddingInlineStart
paddingInlineStart
< | "">
Default: '' - meaning no override

The inline-start padding (left in LTR writing modes, right in RTL).

Overrides the inline-start value from paddingInline.

Anchor to ExamplesExamples

Anchor to Style a container with background and paddingStyle a container with background and padding

Create a styled container with background, border, and padding. This example shows an s-box with subdued background, rounded corners, and base-level padding around paragraph text.

Style a container with background and padding

A rendered example of the box component

html

<s-box
background="subdued"
borderRadius="base"
borderWidth="base"
padding="base"
accessibilityLabel="Product notice"
>
<s-paragraph>
Baked fresh to order. Please order 1-2 days before needed due to potential
shipping variations.
</s-paragraph>
</s-box>

Anchor to Highlight a callout with a bordered boxHighlight a callout with a bordered box

Create a prominent callout by combining background, border, and large padding. This example applies background="base", border, borderRadius="large", and padding="large" with an accessibilityLabel for assistive technology.

html

<s-box
background="base"
border="base"
borderRadius="large"
padding="large"
accessibilityLabel="Important notice"
>
<s-paragraph>
Review your order details carefully. Changes can't be made after checkout.
</s-paragraph>
</s-box>

Anchor to Build layered containers with nested boxesBuild layered containers with nested boxes

Nest styled containers to build layered visual groupings. This example uses an outer s-box with a subdued background, an accessibilityLabel, and inner boxes for each content item.

html

<s-box padding="base" background="subdued" borderRadius="base" accessibilityLabel="Product details">
<s-stack gap="small">
<s-text type="strong">Product details</s-text>
<s-box padding="small" background="base" borderRadius="base">
<s-text>Size: Medium</s-text>
</s-box>
<s-box padding="small" background="base" borderRadius="base">
<s-text>Color: Navy</s-text>
</s-box>
</s-stack>
</s-box>

Anchor to Best practicesBest practices

  • Use box for styling, not layout: Box applies visual properties like backgrounds, borders, and padding. For arranging elements in rows or columns, use stack or grid.
  • Preserve natural sizing: Use box inside layout components to prevent children from stretching. Box contents maintain their natural dimensions.
  • Keep nesting shallow: Avoid deeply nested boxes. If you need complex layouts, reach for grid or stack instead.
  • Prefer semantic components when available: Use section for content groups with headings, or divider for visual separation, before using box.
  • Combine styling properties: Pair background, border, borderRadius, and padding to create distinct visual zones.
Was this page helpful?