# usePickerModal

**Category:** Base Components/Collections/Picker/Hooks

## API

### Description

`usePickerModal` is a React hook that creates the state for a [`PickerModal`](./?path=/story/base-components-picker--pickermodal). It accepts picker configuration (query name, fetch data, filters, pagination, selection callback) and a lazy-loaded `pickerContentComponent`. Import from the entry point that matches your environment.

```tsx
import { usePickerModal } from '@wix/patterns/bm';
```

```tsx
import { usePickerModal } from '@wix/patterns/giza';
```

```tsx
import { usePickerModal } from '@wix/patterns/essentials';
```

---

### Example

```tsx
import { usePickerModal, PickerModal } from '@wix/patterns/bm';

const pickerState = usePickerModal({
  queryName: 'my-picker',
  fetchData: (query) => fetchItems(query),
  limit: 50,
  onSelect: (items) => handleSelect(items),
  pickerContentComponent: () => import('./MyPickerContent'),
});

return (
  <>
    Open Picker
    
  
);
```

### Returns

`PickerModalState` — pass it to ``.

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `environment` | `Environment` | Yes | - | The user's environment - `language` - preferable language for the user |
| `errorMonitor` | `ErrorMonitor` | Yes | - | A `ErrorMonitor` instance `@wix/fe-essentials/error-monitor` |
| `biLoggerFactory` | `(options?: (FactoryOptions & { trackSession?: boolean \| "force" \| undefined; }) \| undefined) => Factory` | Yes | - | A `BILoggerFactory` instance `@wix/fe-essentials/bi` |
| `limit` | `number` | No | - | Number of items to fetch on each page |
| `filters` | `Partial<RawFiltersParams<F>>` | No | - | Defines the initial values and config for filters that the collection supports. For example: { premium: {initialValue: 'true'} } |
| `fetchInitialProps` | `(() => Promise<unknown>)` | No | - | Optional function that loads more dependencies required for the content of the modal to show. The modal will keep showing a loader when this promise is still pending. For example custom i18n translations. |
| `onSelect` | `(items: T[], options: OnSelectOptions<T>) => unknown` | Yes | - | A function being called after clicking the primary button of the modal. It accepts the following parameters: - `items` - The items that were selected in the modal's internal selector list - `options.isSelectAll` - Indicates the user toggled on the "Select All" checkbox (relevant only when `showSelectAllCheckbox` is passed to `<PickerContent />`) - `options.selectedCount` - The number of items the user selected. Subtracts from total count the items that were unchecked after toggling on the "Select All" checkbox - `options.uncheckedValues` - The items the user unchecked after toggling on the "Select All" checkbox (relevant only when `showSelectAllCheckbox` is passed to `<PickerContent />`) - `options.partiallySelectedIds` - Selected items in indeterminate status |
| `pickerContentComponent` | `() => Promise<{ default: PickerContentComponent<T, F>; }>` | Yes | - | A function that returns a promise of dynamically imported component that renders [`<PickerContent `/>](./?path=/story/base-components-collections-picker--pickercontent) internally |
| `events` | `PickerModalEvents` | No | - | Optional callbacks for various events of the picker modal lifecycle `onError` - when there's an error fetching initial data, picker content chunk or initial props. |
| `paginationMode` | `"cursor" \| "offset"` | No | `offset` | Indicates what type of pagination the `fetchData` function supports.<br> In case the server accepts the `query.offset` parameter - pass `'offset'` In case the server returns a `cursor` from `fetchData` - pass `'cursor'` |
| `queryName` | `string` | Yes | - | The query name used for cache purposes. This should be a unique value per API endpoint consumed inside the `fetchData` function.<br> It's recommended to use the [Fqdn](https://bo.wix.com/wix-docs/rnd/p13n-guidelines---aips/guidance-aips/wix-api-basics/[1009]-fqdn) of the service used in `fetchData` as `queryName` |
| `fetchData` | `((query: ComputedQuery<F>) => Promise<DataResultRaw<T>>)` | No | - | A function that integrates with the API to fetch the collection data from.<br> Accepts the following parameters: - `query`: A [ComputedQuery](./?path=/story/common-types--computedquery) instance. Holds all the relevant variables to query the server API with. The function must return a promise of [DataResultRaw](./?path=/story/common-models--dataresultraw) |
| `skipFirstPagePrefetch` | `boolean` | No | - | In the picker modal, the data is prefetched before the user opens the modal. This flag disables this behavior. |
| `disableAutoSelectOnSingleItem` | `boolean` | No | - | A flag to disable default behavior when fetch data returns a single item. Instead of calling onSelect a dialog will be opened. |