--- title: Scroll box description: >- Provides a scrollable container for long content that exceeds the available space. Use to display lists, order summaries, or other lengthy content while maintaining a constrained layout. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/scroll-box md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/scroll-box.md --- # Scroll box Provides a scrollable container for long content that exceeds the available space. Use to display lists, order summaries, or other lengthy content while maintaining a constrained layout. ### Support Targets (29) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## Properties * **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'** Changes the visibility of the element. * `visible`: the element is visible to all users. * `hidden`: the element is removed from the accessibility tree but remains visible. * `exclusive`: the element is visually hidden but remains in the accessibility tree. * **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. * **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}` ``` ### ScrollBoxProps * accessibilityLabel 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. ```ts string ``` * accessibilityRole The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page. ```ts AccessibilityRole ``` * accessibilityVisibility Changes the visibility of the element. - \`visible\`: the element is visible to all users. - \`hidden\`: the element is removed from the accessibility tree but remains visible. - \`exclusive\`: the element is visually hidden but remains in the accessibility tree. ```ts 'visible' | 'hidden' | 'exclusive' ``` * background 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). ```ts 'base' | 'subdued' | 'transparent' ``` * blockSize 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. ```ts MaybeResponsive ``` * border 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. ```ts BorderShorthand ``` * borderColor The color of the border using the design system's color scale. Overrides the color value set by \`border\`. ```ts '' | 'base' ``` * borderRadius 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. ```ts MaybeAllValuesShorthandProperty> ``` * borderStyle 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 ```ts MaybeAllValuesShorthandProperty | "" ``` * borderWidth 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\`. ```ts MaybeAllValuesShorthandProperty | '' ``` * display 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. ```ts MaybeResponsive<"auto" | "none"> ``` * id 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. ```ts string ``` * inlineSize 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. ```ts MaybeResponsive ``` * maxBlockSize 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). ```ts MaybeResponsive ``` * maxInlineSize 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). ```ts MaybeResponsive ``` * minBlockSize 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). ```ts MaybeResponsive ``` * minInlineSize 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). ```ts MaybeResponsive ``` * overflow 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). ```ts OverflowKeyword | `${OverflowKeyword} ${OverflowKeyword}` ``` * padding 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. ```ts MaybeResponsive> ``` * paddingBlock 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\`. ```ts MaybeResponsive | ""> ``` * paddingBlockEnd The block-end padding (bottom in horizontal writing modes). Overrides the block-end value from \`paddingBlock\`. ```ts MaybeResponsive ``` * paddingBlockStart The block-start padding (top in horizontal writing modes). Overrides the block-start value from \`paddingBlock\`. ```ts MaybeResponsive ``` * paddingInline 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\`. ```ts MaybeResponsive | ""> ``` * paddingInlineEnd The inline-end padding (right in LTR writing modes, left in RTL). Overrides the inline-end value from \`paddingInline\`. ```ts MaybeResponsive ``` * paddingInlineStart The inline-start padding (left in LTR writing modes, right in RTL). Overrides the inline-start value from \`paddingInline\`. ```ts MaybeResponsive ``` ### 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 ## Preview ![](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/scroll-box-default-wTxhdGqT.png) ### Examples * #### Code ##### Default ```html ```