Skip to main content

Scroll box

The scroll box component provides a scrollable container for long content that exceeds the available space. Use scroll box to display lists, order summaries, or other lengthy content while maintaining a constrained layout.

Scroll box supports maximum height constraints, background styling, and border properties to create bounded content areas. For layouts where all content should be visible without scrolling, use stack or box.

Scroll box defaults to vertical scrolling and doesn't emit scroll position events. To enable horizontal scrolling, use the two-value overflow syntax (for example, hidden auto). If you need scroll-position events, consider the React-based ScrollView component in the 2025-07 API.

Support
Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the scroll 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 scroll 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, borderColor) can override values set here.

Anchor to borderColor
borderColor
'' | 'base'
Default: '' - meaning no override

The color of the border using the design system's color scale. Overrides the color value set by border.

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

The roundedness of the scroll 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
| `${} ${}`
Default: 'auto'

The overflow behavior of the scroll box, controlling whether content that exceeds the container is scrollable or clipped. Learn more about overflow.

  • hidden: Content is clipped and the element is not scrollable in that axis.
  • auto: Content is clipped and becomes scrollable in that axis.

Supports 1-to-2-value syntax using flow-relative axes. Two values are ordered as block inline (for example, hidden auto clips vertically and scrolls horizontally).

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 Display a scrollable listDisplay a scrollable list

Set maxBlockSize to constrain the container height and enable scrolling. This example shows a list of order line items that scrolls when the content exceeds 120px.

Display a scrollable list

A scrollable container with overflow content and fade indicators at the edges.

html

<s-scroll-box maxBlockSize="120px">
<s-stack direction="block" gap="small-200">
<s-text>Mini garden seeds — $35.00</s-text>
<s-divider></s-divider>
<s-text>Ceramic planter — $22.00</s-text>
<s-divider></s-divider>
<s-text>Potting soil (5 lb) — $12.00</s-text>
<s-divider></s-divider>
<s-text>Watering can — $18.00</s-text>
<s-divider></s-divider>
<s-text>Plant food — $8.00</s-text>
</s-stack>
</s-scroll-box>

Anchor to Constrain tall contentConstrain tall content

Use scroll box to prevent tall content blocks from dominating the page layout. This example constrains three colored boxes within a 100px scrollable area.

html

<s-scroll-box maxBlockSize="100px">
<s-box background="subdued" border="base" minBlockSize="50px" padding="base">
<s-text>Section 1</s-text>
</s-box>
<s-box background="subdued" border="base" minBlockSize="50px" padding="base">
<s-text>Section 2</s-text>
</s-box>
<s-box background="subdued" border="base" minBlockSize="50px" padding="base">
<s-text>Section 3</s-text>
</s-box>
</s-scroll-box>

Anchor to Add an accessible scrollable regionAdd an accessible scrollable region

Set accessibilityLabel to describe the scrollable content for screen reader users. This example shows an order activity timeline with delivery tracking events.

html

<s-scroll-box maxBlockSize="150px" accessibilityLabel="Order activity history">
<s-stack direction="block" gap="base">
<s-stack direction="block" gap="small-200">
<s-text type="strong">Delivered</s-text>
<s-text>March 18, 2025 — Package left at front door</s-text>
</s-stack>
<s-divider></s-divider>
<s-stack direction="block" gap="small-200">
<s-text type="strong">Out for delivery</s-text>
<s-text>March 18, 2025 — With local courier</s-text>
</s-stack>
<s-divider></s-divider>
<s-stack direction="block" gap="small-200">
<s-text type="strong">In transit</s-text>
<s-text>March 16, 2025 — Departed Toronto facility</s-text>
</s-stack>
<s-divider></s-divider>
<s-stack direction="block" gap="small-200">
<s-text type="strong">Shipped</s-text>
<s-text>March 15, 2026 — Label created</s-text>
</s-stack>
</s-stack>
</s-scroll-box>

Anchor to Best practicesBest practices

  • Set a reasonable max height: Choose a maxBlockSize that shows enough content for context while keeping the page layout manageable. Showing 2-3 visible items before scrolling gives customers a clear indication that more content is available.
  • Provide an accessibility label: Set accessibilityLabel to describe the scrollable region so screen reader users understand what content is scrollable.
  • Don't nest scroll boxes: Avoid placing scroll boxes inside other scroll boxes. Nested scrollable regions create confusing navigation, especially for keyboard and assistive technology users.
Was this page helpful?