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 boxes support axis-specific scrolling, max sizes, and overflow modes that clip or reveal scrollbars. For grouped content with headings and landmarks, use section instead.

Scroll box doesn't support scroll snapping or programmatic scroll-to behavior. The scroll indicator styling is determined by the platform and can't be customized.

Support
Targets (29)

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 Constrain content in a scrollable areaConstrain content in a scrollable area

Contain overflowing content within a scrollable region. This example sets maxBlockSize to 120px on s-scroll-box so the boxes scroll inside the frame.

Constrain content in a scrollable area

A rendered example of the scroll-box component

html

<s-scroll-box maxBlockSize="120px">
<s-stack direction="block" gap="small">
<s-box background="subdued" border="base" padding="base"></s-box>
<s-box background="subdued" border="base" padding="base"></s-box>
<s-box background="subdued" border="base" padding="base"></s-box>
<s-box background="subdued" border="base" padding="base"></s-box>
<s-box background="subdued" border="base" padding="base"></s-box>
</s-stack>
</s-scroll-box>

Anchor to Clip overflowing content without scrollingClip overflowing content without scrolling

Clip content that exceeds the container without displaying a scrollbar. This example sets overflow="hidden" and a small maxBlockSize on s-scroll-box so only the first portion of text is visible.

html

<s-scroll-box maxBlockSize="20px" overflow="hidden">
<s-stack direction="block" gap="small">
<s-text>This text is clipped because the scroll box has a small max block size and overflow is set to hidden.</s-text>
<s-text>This second line is completely hidden from view.</s-text>
<s-text>This third line is also hidden.</s-text>
</s-stack>
</s-scroll-box>

Anchor to Scroll a long list of cart itemsScroll a long list of cart items

Constrain a long list of cart items within a scrollable area. This example lists divider-separated rows inside s-scroll-box with maxBlockSize to keep checkout compact.

html

<s-scroll-box maxBlockSize="100px">
<s-stack gap="small">
<s-text>Organic cotton t-shirt × 2</s-text>
<s-divider></s-divider>
<s-text>Recycled denim jeans × 1</s-text>
<s-divider></s-divider>
<s-text>Wool beanie × 1</s-text>
<s-divider></s-divider>
<s-text>Canvas tote bag × 1</s-text>
<s-divider></s-divider>
<s-text>Bamboo sunglasses × 1</s-text>
<s-divider></s-divider>
<s-text>Linen scarf × 1</s-text>
</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 two to three visible items before scrolling gives buyers a clear indication that more content is available.
  • Provide an accessibility label: Set accessibilityLabel to describe the scrollable region so buyers using assistive technology understand what content is scrollable.
  • Choose the right overflow mode: Use auto for navigable content and hidden when clipping is intentional.
  • 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.
  • Pair with dividers inside lists: Separate dense rows with s-divider so scrolling content stays scannable.
Was this page helpful?