@payfit/unity-components
Version:
96 lines (95 loc) • 4.69 kB
TypeScript
import { JSX, Ref } from 'react';
import { ListBoxProps as AriaListBoxProps } from 'react-aria-components/ListBox';
/**
* Props for the SelectList component.
* @template TType - The type of items in the list
*/
export interface SelectListProps<TType extends object = object> extends Omit<AriaListBoxProps<TType>, 'className' | 'style' | 'selectedKeys' | 'onSelectionChange' | 'children'> {
/**
* An iterable data structure containing items to render in the list.
*/
items: Iterable<TType>;
/**
* Render function for each item. Receives an item and should generally returns a `SelectListOption` component.
*/
children: (item: TType) => React.ReactElement;
/**
* The current selected keys of the list. Pass a `Set` of keys to control the selection state.
*/
value: AriaListBoxProps<TType>['selectedKeys'];
/**
* Callback function invoked when the user selection changes. Use this to update the controlled `value` prop.
* @param keys - The new selection as a `Selection` type (Set of keys or "all")
*/
onChange: AriaListBoxProps<TType>['onSelectionChange'];
/**
* Controls whether to display a search input at the top of the list. Set to `true` to always show the search bar, or `false` to never show it. When undefined, the search bar appears automatically when there are 10 or more items.
* @default undefined - Auto-shows when items >= 10
*/
showSearch?: boolean;
/**
* Additional CSS classes to apply to the list container. Use this to customize height or other container styles.
*/
className?: string;
/**
* Enables selected-first sorting, which moves selected items into a dedicated section at the top of the list. Selected items can be deselected directly from this section.
* @default false
*/
sortSelectedFirst?: boolean;
/**
* Accessible label for the selected items section. This label is screen-reader only and provides context for the separated selected items.
* @default "Selected"
*/
selectedSectionLabel?: string;
/**
*
*/
isLoading?: boolean;
}
type SelectListComponent = {
<TType extends object>(props: SelectListProps<TType> & {
ref?: Ref<HTMLDivElement>;
}): JSX.Element;
displayName: string;
};
/**
* Provides a high-performance, accessible list for selecting items with built-in virtualization, search, and sorting capabilities.
* Use this component to allow users to select one or multiple items from a list of options. The component automatically handles large datasets through virtualization, provides built-in search functionality when needed, and can optionally organize selected items into a dedicated section at the top for better visibility.
* @param {SelectListProps} props - Regular props from React Aria's ListBox, plus selection, search, and sorting configuration
* @example
* ```tsx
* import { SelectList, SelectListOption } from '@payfit/unity-components'
*
* function FruitSelector() {
* const [selected, setSelected] = useState(new Set())
* const fruits = [
* { id: 'apple', label: 'Apple' },
* { id: 'banana', label: 'Banana' }
* ]
*
* return (
* <SelectList
* items={fruits}
* value={selected}
* onChange={setSelected}
* selectionMode="multiple"
* >
* {item => <SelectListOption id={item.id}>{item.label}</SelectListOption>}
* </SelectList>
* )
* }
* ```
* @remarks
* - List items are automatically virtualized for optimal performance with large datasets (hundreds or thousands of items)
* - Search bar appears automatically when the list contains 10 or more items, or can be controlled via the `showSearch` prop
* - Set `sortSelectedFirst` to `true` to move selected items into a dedicated section at the top of the list
* - The component requires the dynamic API pattern: provide both `items` array and a render function as `children`
* - Selection state is fully controlled via the `value` and `onChange` props following React's controlled component pattern
* - Supports both flat item lists and grouped sections using `SelectListOptGroup`
* @see {@link SelectListProps} for all available props
* @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/select-list GitHub}
* @see Design specs in {@link https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library Figma}
* @see Developer docs in {@link https://unity-components.payfit.io/?path=/docs/data-selectlist unity-components.payfit.io}
*/
declare const SelectList: SelectListComponent;
export { SelectList };