Loading navigation…
User
API and Development
Import sort/group and filter surfaces from @prepared911/ui-filters. Props below are documented with manual tables — this package uses flat/src/sort layouts that are outside the docs component-api registry / DocgenPropsTable discovery.
SortControl is a discriminated union on variant.
| Name | Type | Default | Description |
|---|---|---|---|
variant | SortVariant.Multiple | Multiple | Criterion menu. |
criteria | SortCriterion<T>[] | required | Sort options. Prefer module-stable or useMemo'd arrays. |
value | SortValue | — | Controlled sort value. Empty criterionId means no active sort. |
defaultValue | SortValue | first criterion ascending | Uncontrolled initial sort. |
onChange | (value: SortValue) => void | — | Sort change handler (including clear → criterionId: ""). |
grouping | GroupCriterion<T>[] | — | When set, renders group menu in a ButtonGroup before sort. |
groupValue | string | null | — | Controlled group criterion id; null = ungrouped. |
defaultGroupValue | string | null | null | Uncontrolled initial group. |
onGroupChange | (groupId: string | null) => void | — | Group change handler. |
label | string | localized "Sort By" | Sort menu / Simple title override. |
groupLabel | string | localized "Group By" | Group menu label override. |
aria-label | string | localized "Sort and group" | ButtonGroup accessible name when grouping is set. |
size | IconButtonSize | — | Icon button size for triggers. |
className | string | — | Root class. |
| Name | Type | Default | Description |
|---|---|---|---|
variant | SortVariant.Simple | required | Direction toggle for one criterion. |
criterion | SortControlSimpleCriterion<T> | required | Exactly one toggleable criterion (fixedDirection is not part of this type). Shared value/label/grouping props match Multiple. |
SortControl embeds useSortState. Sort is controlled when value !== undefined; group is controlled when groupValue !== undefined — axes may differ.
| Name | Type | Description |
|---|---|---|
id | string | Stable id (persistable). |
label | string | Menu / title label. |
icon | SVGAsset | Optional; not rendered in the Multiple sort menu (labels only). |
field | keyof T & string | Shorthand field compare. |
compare | (a, b) => number | Ascending comparator; wins over field. |
fixedDirection | SortDirection | Pins direction and hides the trailing direction control while selected. |
disabled | boolean | Disables the criterion option. |
| Name | Type | Description |
|---|---|---|
id | string | Stable id (persistable). |
label | string | Group menu label. |
icon | SVGAsset | Decorative leading icon. |
getKey | (item) => string | string[] | null | undefined | Multi-key allowed; nullish → ungrouped. |
getLabel | (key, items) => string | Optional bucket label. |
compareGroups | (a, b) => number | Optional group ordering. |
disabled | boolean | Disables the option. |
Group rows are toggleable menuitemcheckbox options with a bare checkmark indicator. Public ungrouped state is groupValue === null (no sentinel export). useSortState.toggleGroup enforces single-select: activating the checked id clears to null.
Controlled/uncontrolled sort + group selection (like useFilterState). Exposes toggleCriterion, setGroup, and toggleGroup.
(criterionId: string) => void — if criterionId matches the active criterion, clears to criterionId: ""; otherwise selects that id (honoring fixedDirection).
(groupId: string) => void — if groupId matches the active group, clears to null; otherwise selects that id.
Embeds useSortState and returns memoised sortedData (like useFilteredData). Sorting is non-mutating (toSorted).
Transform-only: { data, grouping, groupId } → { groups, ungrouped }. Pass groupId from state / SortControl.
Filter (search, categories, quick filters, segmented control, column visibility) lives in this package. Full prop tables currently remain under Data Table API with a cross-link pointing back here as the package home. Prefer:
debounceSearchMs: omit or 0 for immediate updates (not 300).