--- title: Scroll box description: >- Provides a scrollable container for long content that exceeds the available space. api_version: 2026-07-rc source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/web-components/layout-and-structure/scroll-box md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/web-components/layout-and-structure/scroll-box.md api_name: checkout-ui-extensions --- # 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](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/web-components/layout-and-structure/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 * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-cart-line-list-) * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#thank-you-cart-line-list-) * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/header#header-target) #### Use cases * **Scrollable content**: Constrain long lists, order summaries, or item details within a fixed scrollable area * **Clipped content**: Hide overflow without displaying a scrollbar by setting `overflow="hidden"` *** ## Properties Configure the following properties on the scroll box component. * **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. * **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. * **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. * **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). * **blockSize** **MaybeResponsive\** **Default: 'auto'** The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **border** **BorderShorthand** **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. * **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`. * **borderRadius** **MaybeAllValuesShorthandProperty\>** **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. * **borderStyle** **MaybeAllValuesShorthandProperty\ | ""** **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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) 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 * **borderWidth** **MaybeAllValuesShorthandProperty\ | ''** **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`. * **display** **MaybeResponsive<"auto" | "none">** **Default: 'auto'** Sets the outer display type of the component. The outer type sets a component’s participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_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](https://developer.mozilla.org/en-US/docs/Web/CSS/display). * **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. * **inlineSize** **MaybeResponsive\** **Default: 'auto'** The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **maxBlockSize** **MaybeResponsive\** **Default: 'none'** The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * **maxInlineSize** **MaybeResponsive\** **Default: 'none'** The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * **minBlockSize** **MaybeResponsive\** **Default: '0'** The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * **minInlineSize** **MaybeResponsive\** **Default: '0'** The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * **overflow** **OverflowKeyword | \`${OverflowKeyword} ${OverflowKeyword}\`** **Default: 'auto'** The overflow behavior of the scroll box, controlling whether content that exceeds the container is scrollable or clipped. Learn more about [`overflow`](https://developer.mozilla.org/en-US/docs/Web/CSS/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). * **padding** **MaybeResponsive\>** **Default: 'none'** The padding applied to all edges of the component. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) 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. * **paddingBlock** **MaybeResponsive\ | "">** **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`. * **paddingBlockEnd** **MaybeResponsive\** **Default: '' - meaning no override** The block-end padding (bottom in horizontal writing modes). Overrides the block-end value from `paddingBlock`. * **paddingBlockStart** **MaybeResponsive\** **Default: '' - meaning no override** The block-start padding (top in horizontal writing modes). Overrides the block-start value from `paddingBlock`. * **paddingInline** **MaybeResponsive\ | "">** **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`. * **paddingInlineEnd** **MaybeResponsive\** **Default: '' - meaning no override** The inline-end padding (right in LTR writing modes, left in RTL). Overrides the inline-end value from `paddingInline`. * **paddingInlineStart** **MaybeResponsive\** **Default: '' - meaning no override** The inline-start padding (left in LTR writing modes, right in RTL). Overrides the inline-start value from `paddingInline`. ### AccessibilityRole The semantic role of a component, used by assistive technologies to convey the element’s purpose to users. Each role maps to a specific HTML element or ARIA role. - \`main\`: The primary content of the page. - \`header\`: A page or section header. - \`footer\`: Information such as copyright, navigation links, and privacy statements. - \`section\`: A generic section that should have a heading or \`accessibilityLabel\`. - \`aside\`: Supporting content related to the main content. - \`navigation\`: A major group of navigation links. - \`ordered-list\`: A list of ordered items. - \`list-item\`: An item inside a list. - \`list-item-separator\`: A divider between list items. - \`unordered-list\`: A list of unordered items. - \`separator\`: A divider that separates sections of content. - \`status\`: A live region with advisory information that is not urgent. - \`alert\`: Important, usually time-sensitive information. - \`generic\`: A nameless container with no semantic meaning (renders a \`\
\`). - \`presentation\`: Strips semantic meaning while keeping visual styling. Synonym for \`none\`. - \`none\`: Strips semantic meaning while keeping visual styling. Synonym for \`presentation\`. ```ts "main" | "header" | "footer" | "section" | "aside" | "navigation" | "ordered-list" | "list-item" | "list-item-separator" | "unordered-list" | "separator" | "status" | "alert" | "generic" | "presentation" | "none" ``` ### MaybeResponsive Makes a property responsive by allowing it to be set conditionally based on container query conditions. The value can be either a base value or a container query string. - \`T\`: Base value that applies in all conditions. - \`@container${string}\`: Container query string for conditional responsive styling based on container size. ```ts T | `@container${string}` ``` ### SizeUnitsOrAuto Represents size values that can also be set to \`auto\` for automatic sizing. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`auto\`: Automatically sizes based on content and layout constraints. Learn more about the \[auto value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/width#auto). ```ts SizeUnits | "auto" ``` ### SizeUnits Represents size values in pixels, percentages, or zero. - \`\` \`${number}px\` \`\`: Absolute size in pixels for fixed dimensions (such as \`100px\`, \`24px\`). - \`\` \`${number}%\` \`\`: Relative size as a percentage of the parent container (such as \`50%\`, \`100%\`). - \`0\`: Zero size, equivalent to no dimension. ```ts `${number}px` | `${number}%` | `0` ``` ### BorderShorthand A shorthand string for specifying border properties. Accepts a size alone (\`'base'\`), size with color (\`'base base'\`), or size with color and style (\`'base base dashed'\`). Omitted values use their defaults. ```ts ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}` ``` ### ReducedBorderSizeKeyword The subset of border size values available for this component. - \`base\`: Standard border width. - \`large\`: Thick border for strong emphasis. - \`large-100\`: Extra thick border for maximum prominence. - \`large-200\`: The thickest available border. - \`none\`: No border. ```ts 'large' | 'base' | 'large-100' | 'large-200' | 'none' ``` ### ReducedColorKeyword The subset of border color values available for this component. - \`base\`: The standard border color for most contexts. ```ts 'base' ``` ### BorderStyleKeyword The visual style of a border. Learn more about \[border-style]\(https://developer.mozilla.org/en-US/docs/Web/CSS/border-style). - \`none\`: No border is rendered. - \`solid\`: A single continuous line. - \`dashed\`: A series of short dashes. - \`dotted\`: A series of round dots. - \`auto\`: The border style is determined automatically based on the surface's design system. ```ts "none" | "solid" | "dashed" | "dotted" | "auto" ``` ### MaybeAllValuesShorthandProperty Represents CSS shorthand properties that accept one to four values, following the \[CSS shorthand syntax]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box). Supports specifying values for all four sides: top, right, bottom, and left. - \`T\`: Single value that applies to all four sides. - \`${T} ${T}\`: Two values for block axis (top/bottom) and inline axis (left/right). - \`${T} ${T} ${T}\`: Three values for block-start (top), inline axis (left/right), and block-end (bottom). - \`${T} ${T} ${T} ${T}\`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left). ```ts T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}` ``` ### SizeUnitsOrNone Represents size values that can also be set to \`none\` to remove the size constraint. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`none\`: No size constraint, allowing unlimited growth. Learn more about the \[none value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/max-width#none). ```ts SizeUnits | "none" ``` ### OverflowKeyword ```ts "auto" | "hidden" ``` ### PaddingKeyword Defines the padding size for elements, using the standard size scale or \`none\` for no padding. - \`SizeKeyword\`: Standard padding sizes from the size scale for consistent spacing. - \`none\`: No padding. ```ts SizeKeyword | "none" ``` ### SizeKeyword The design system's size scale, used to control the dimensions of components like avatars, icons, and thumbnails. Values range from \`"small-500"\` (smallest) through \`"base"\` (standard) to \`"large-500"\` (largest). Not all components support every size — check the component's \`size\` property type for its available options. ```ts "small-500" | "small-400" | "small-300" | "small-200" | "small-100" | "small" | "base" | "large" | "large-100" | "large-200" | "large-300" | "large-400" | "large-500" ``` ### MaybeTwoValuesShorthandProperty Represents CSS shorthand properties that accept one or two values. Supports specifying the same value for both dimensions or different values. - \`T\`: Single value that applies to both dimensions. - \`${T} ${T}\`: Two values for block axis (vertical) and inline axis (horizontal). ```ts T | `${T} ${T}` ``` *** ## Examples ### Constrain 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](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/scroll-box-default-wTxhdGqT.png) ## html ```html ``` ### Clip 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 ```html This text is clipped because the scroll box has a small max block size and overflow is set to hidden. This second line is completely hidden from view. This third line is also hidden. ``` ### Scroll 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 ```html Organic cotton t-shirt × 2 Recycled denim jeans × 1 Wool beanie × 1 Canvas tote bag × 1 Bamboo sunglasses × 1 Linen scarf × 1 ``` *** ## Best 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. ***