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 |
|---|
| Name | Type | Description | Default |
|---|
| Name | Type | Description | Default |
|---|
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.