SKUMatrix
Displays a table of product variations with quantity selectors for bulk purchases.
The
SKUMatrix component displays a table of product variations with quantity selectors, enabling customers to add multiple SKUs to the cart at once. This component is ideal for B2B scenarios or bulk purchasing.The final component is a compound of the following:
SKUMatrix: Wraps the SKU Matrix structure that provides context and state management.SKUMatrixTrigger: Renders a button that opens the SKU Matrix sidebar.SKUMatrixSidebar: Renders aSlideOvercontaining a table with product variations, prices, availability, and quantity selectors.
Example
Code
Usage
Import the component
Import the compound from @faststore/ui.
_10import {_10 SKUMatrix,_10 SKUMatrixTrigger,_10 SKUMatrixSidebar,_10 useSKUMatrix,_10} from "@faststore/ui";
Import styles
Add the sidebar styling tokens and layout rules to your theme stylesheet:
_10@import "@faststore/ui/src/components/organisms/SKUMatrix/styles.scss";
Follow the Importing FastStore UI component styles instructions. Additionally, the quantity selector, badges, and table components rely on their respective partials.
Examples
Loading State
While fetching product variants, display skeleton loaders to improve perceived performance by setting
loading={true} on SKUMatrixSidebar.Example
Code
Full Width Sidebar
Display the matrix in a full-width slide-over for complex product catalogs with many columns by setting
size="full".Example
Code
Left Side Direction
Open the sidebar from the left side of the screen by setting
direction="leftSide".Example
Code
Design tokens
| Local token | Default value/Global token linked |
|---|---|
--fs-sku-matrix-sidebar-bkg-color | var(--fs-color-body-bkg) |
--fs-sku-matrix-sidebar-title-size | var(--fs-text-size-6) |
--fs-sku-matrix-sidebar-title-text-weight | var(--fs-text-weight-semibold) |
--fs-sku-matrix-sidebar-table-cell-font-size | var(--fs-text-size-tiny) |
--fs-sku-matrix-sidebar-table-cell-text-weight | var(--fs-text-weight-medium) |
--fs-sku-matrix-sidebar-table-cell-image-width | var(--fs-spacing-7) |
--fs-sku-matrix-sidebar-table-cell-image-border-radius | var(--fs-border-radius) |
--fs-sku-matrix-slide-over-partial-gap | calc(2 * var(--fs-grid-padding)) |
--fs-sku-matrix-slide-over-partial-width-mobile | calc(100vw - var(--fs-sku-matrix-slide-over-partial-gap)) |
Data attributes
Use these selectors to customize styles or attach test logic:
data-fs-sku-matrixdata-testid="fs-sku-matrix"data-fs-sku-matrix-sidebardata-fs-sku-matrix-sidebar-titledata-fs-sku-matrix-sidebar-cell-imagedata-fs-sku-matrix-sidebar-table-pricedata-fs-sku-matrix-sidebar-table-cell-quantity-selectordata-fs-sku-matrix-sidebar-table-actiondata-fs-sku-matrix-sidebar-footer- SlideOver attributes propagated to the sidebar:
data-fs-slide-over,data-fs-slide-over-direction,data-fs-slide-over-size,data-fs-slide-over-state
Props
| Name | Type | Description | Default |
|---|---|---|---|
| testId | string | ID to find this component in testing tools (e.g.: cypress, testing library, and jest). | fs-sku-matrix |
| Name | Type | Description | Default |
|---|---|---|---|
| testId | string | ID to find this component in testing tools (e.g.: cypress, testing library, and jest). | |
| variant | "primary" | "secondary" | "tertiary" | Specifies the component color variant. | secondary |
| size | "small" | "regular" | Specifies the size variant. | |
| inverse | false | true | Defines the use of inverted colors. | |
| disabled | false | true | Specifies that this button should be disabled. | |
| icon | string | number | false | true | {} | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | A React component that will be rendered as an icon. | |
| loading | false | true | Boolean that represents a loading state. | |
| loadingLabel | string | Specifies a label for loading state. | |
| iconPosition | "left" | "right" | Specifies where the icon should be positioned |
| Name | Type | Description | Default |
|---|---|---|---|
| title | string | Title for the SKUMatrixSidebar component. | |
| columns* | VariationProductColumn | Represents the variations products to building the table. | |
| buyProps* | { 'data-testid': string; 'data-sku': string; 'data-seller': string; onClick(e: React.MouseEvent<HTMLButtonElement>): void; } | Properties related to the 'add to cart' button | |
| formatter | PriceFormatter | Formatter function that transforms the raw price value and render the result. | |
| loading | false | true | Check if some result is still loading before render the result. | |
| ImageComponent | FunctionComponent<{ src: string; alt: string; width?: number; height?: number; }> | Function that returns a React component that will be used to render images. | ({
src,
alt,
...otherProps
}) => <img src={src} alt={alt} {...otherProps} /> |
| aria-labelledby | string | Identifies the element (or elements) that labels the current element. @see aria-labelledby https://www.w3.org/TR/wai-aria-1.1/#aria-labelledby | |
| children* | string | number | false | true | {} | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Children or function as a children. | |
| testId | string | ID to find this component in testing tools (e.g.: cypress, testing library, and jest). | |
| onEntered | () => void | Callback function when the modal is opened. | |
| onDismiss | () => void | This function is called whenever the user clicks outside. the modal content | |
| overlayProps | Props | Props forwarded to the `Overlay` component. | |
| disableEscapeKeyDown | false | true | Disable being closed using the Escape key. | |
| direction | "leftSide" | "rightSide" | Represents the side that the SlideOver comes from. | rightSide |
| size | "full" | "partial" | Represents the size of the SlideOver. | partial |
Best practices
✅ Dos
- Use concise variation labels (example: "Black - 42") to ensure the table remains scannable on partial-width slide-overs.
- Keep price and availability in sync with your store OMS; display a toast message when quantity adjustments are coerced.
- Localize both column headers and toast messages for multinational catalogs.
❌ Don'ts
- Don't expose the matrix when a product is single-SKU; it adds unnecessary friction.
- Don't rely on color alone for stock communication; pair badge colors with descriptive text.
- Don't allow quantities beyond available stock; the component exposes validation hooks for this reason.
- Don't hardcode dimensions; merchants should be able to adjust columns per category via Headless CMS.