Catalogue
Searchable product grid or table with variant choices and stock sync times
Import
import { Catalogue } from '@tallyui/components';Usage
<Catalogue
products={products}
traits={traits}
currency="EUR"
onSelect={(entry) => selectProduct(entry)}
lastSyncedAt={lastSyncedAt}
showViewToggle
showCategoryNav
/>Renders a searchable product grid or table with barcode or SKU lookup, variant choices, and stock sync times. Optional category navigation and a view toggle update controlled or internal view state; supplied items are displayed in their given order. With showFilterBar, In Stock is on by default and hides out-of-stock and backorder products (a stock the backend did not report stays) unless items is supplied; Featured and On Sale are only passed out through onFiltersChange, for an app whose connector knows them. With variationsStyle="popover", a grid tile opens its VariationPicker; with variationsStyle="drill", it swaps the grid for the product's variant tiles, with the product's tile first as Back; the table view keeps the list chooser. In the drill, a "Products › name" crumb sits above the variant tiles, and on web Escape goes back. In drill style a product with more than one variant draws its grid tile stacked, with two cards behind it, and each variant tile shows how many of that variant the cart holds. The cameraScan button shows only when cameraScanner is passed too. With tileFields, a grid tile shows only the words switched on (v2's Tile Fields); without it, tiles show the name, price and stock as before.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
products | Doc[] | required | Product documents used for scanning, variant choices, and the displayed list when items is omitted |
traits | ProductTraits<Doc> | required | Accessors used to read product identity, names, variants, categories, search fields, and sort values |
currency | string | required | Currency used for catalogue entries, variant prices, and price sorting |
onSelect | (entry: CatalogueEntry<Doc>) => void | required | Receives the selected product and variant with the nearest ConnectorProvider's stock overlay applied to a copy |
statusText | string | --- | Status line text; a search appends the number of matching results |
statusAccessory | ReactNode | --- | Content at the end of the status line; renders the row even without statusText |
searchAccessory | ReactNode | --- | Content at the end of the search row, after the camera scan button and the view toggle |
lastSyncedAt | Date | null | required | Last catalogue sync time, used for the stock-as-of time and initial loading state |
loading | boolean | --- | Whether the first pull is running; when omitted, uses lastSyncedAt === null with no pullError |
pullError | unknown | --- | Last product pull error; when set, a never-synced empty catalogue is not treated as loading |
lastStockCheckAt | Date | null | --- | Last completed stock reconcile time; the displayed time is the latest of this, the valid provider overlay time, and lastSyncedAt |
hour12 | boolean | --- | Selects a 12- or 24-hour stock-as-of clock; omission keeps the locale default |
minCodeLength | number | --- | Minimum trimmed search length for Enter to attempt a code lookup; shorter input stays a search |
viewState | CatalogueViewState | --- | Controlled view state; requested changes are reported through onStateChange |
defaultViewState | Partial<CatalogueViewState> | --- | Initial uncontrolled state merged over DEFAULT_CATALOGUE_VIEW_STATE |
loadViewState | () => unknown | Promise<unknown> | --- | Reads app-owned stored state once on mount in uncontrolled mode |
saveViewState | (state: CatalogueViewState) => void | Promise<void> | --- | Saves cashier changes in uncontrolled mode; does not save loads |
onViewStateError | (error: unknown) => void | --- | Receives load and save errors; errors are swallowed when omitted |
onStateChange | (state: CatalogueViewState) => void | --- | Receives loaded state or the cashier's next state, including requested state in controlled mode |
showViewToggle | boolean | false | Shows the grid and table toggle in the header |
showCategoryNav | boolean | false | Shows category navigation in the header |
categoryBrowse | 'chips' | 'tiles' | 'chips' | With showCategoryNav, shows categories as the chip row or as poster tiles with product counts that open under a breadcrumb; the breadcrumb wraps a long category name, collapses to "‹ Categories" on a phone, and on web Escape goes back to the tiles. In a category the first tile is the category itself, and tapping it goes back; a search typed inside a category searches every product |
categories | ProductCategory[] | --- | Replaces categories derived from the listed products |
items | Doc[] | --- | App-filtered and sorted list shown as given; products still drives scanning and variant choices |
onQueryChange | (query: string) => void | --- | Receives search text on each input change for app-owned filtering |
pickAnyOptions | boolean | false | Asks for a value for each of a variant's local "Any" option groups before onSelect; set it only when the store accepts order.create version 6 |
cartLines | readonly (CartQuantityLine & { variantId?: string })[] | --- | The open sale's lines; each grid tile shows an InCartBadge with its product's summed quantity, all variants together; a line's optional variantId lets the drill count each variant |
showFilterBar | boolean | false | Shows a ProductFilterBar under the search box |
filterChips | readonly ProductFilterChip[] | ['inStock'] | Chips the bar shows; Catalogue applies only In Stock itself |
inStockKeepsBackorder | boolean | false | With the In Stock filter on, keeps backorder products in the grid and drops only out-of-stock ones |
termPills | boolean | readonly string[] | false | With showFilterBar, a searchable term pill per term group from traits.getTerms: true for every group, or the group ids to show in that order; one pick per group, groups combine, not saved; not drawn with items |
filters | ProductFilters | --- | Controlled filters; uncontrolled state starts at DEFAULT_PRODUCT_FILTERS (In Stock on) |
onFiltersChange | (filters: ProductFilters) => void | --- | Receives the cashier's next filters, including requested filters in controlled mode |
variationsStyle | 'list' | 'popover' | 'drill' | 'list' | 'popover' opens a grid tile's VariationPicker in a popover for a product with option groups; 'drill' swaps the grid for the product's variant tiles, with its tile first as Back; 'list' opens the variant list chooser |
cameraScan | boolean | false | Shows the camera scan button beside the search box, opening an inline camera scanner panel |
cameraScanner | Omit<CameraScannerPanelProps, 'onClose'> | --- | Passed to the camera scanner panel; the app wires its useCameraScan result here |
tableRow | { thumbnail?: boolean; addButton?: boolean; expand?: boolean; variationsButton?: boolean } | --- | In table view, thumbnail leads each row and addButton ends it with a button that does what a row press does; with expand and thumbnail, a product with more than one variant has its thumbnail show or hide its variants as rows under it, each with its option chips, price, stock and a + that adds that variant as the list chooser does; variationsButton adds v2's “count variations” button under the name, which shows or hides the variants as expand does, and needs expand (TallyUI difference: the variant rows are not laid out on the table's columns, and there is no expand animation) |
rowsSlot | ReactNode | --- | Rows such as notices rendered under the header and above the grid, table, or category tiles |
tileFields | Partial<TileFields> | DEFAULT_TILE_FIELDS | Which words a grid tile shows, merged over the default (name, price with its on-sale strike, stock): name (off keeps the name as the tile's accessibility label), price, onSale, sku, barcode, categories (one line each after the price, only when set) and stock; with stock off, an out-of-stock product still shows its badge while price is on. It also drives the drill's variant tiles (name and option chips, price, sku and barcode, no categories, stock) and the loading skeleton's tile height; the table view ignores it |