Automattic Design System

DataViewsPicker

DataViewsPicker renders a dataset allowing users to select one or multiple items. It shares the layouts, search, and filtering of DataViews but is geared toward choosing items rather than managing them.

import { DataViewsPicker } from '@wordpress/dataviews';

LinksPermalink to this section

View on Storybook

View source on GitHub

PropsPermalink to this section

Name	Default	Description
`view` Required		`View` The current view configuration: layout type, filters, sorting, pagination, search term, and visible fields.
`onChangeView` Required		`(view: View) => void` Callback invoked with the new view whenever the user changes it (filtering, sorting, switching layout, changing page, etc.). Consumers own the view state and must store the new value.
`fields` Required		`Field<SpaceObject>[]` The fields describing each item’s data: how to get and render a value, plus its sorting and filtering capabilities.
`actions`	`[]`	`ActionButton<SpaceObject>[]` The button actions that can be performed on items. Unlike `DataViews`, pickers only support button actions (no modals).
`search`	`true`	`boolean` Whether the global search input is displayed.
`searchLabel`	`undefined`	`string` The accessible label and placeholder for the search input.
`data` Required		`SpaceObject[]` The dataset to render, already filtered, sorted, and paginated according to the current view.
`isLoading`	`false`	`boolean` Whether the data is loading, in which case a loading state is shown.
`paginationInfo` Required		`{ totalItems: number; totalPages: number; }` Pagination totals for the full dataset (not just the current page).
`defaultLayouts`	`{ pickerGrid: true, pickerTable: true, }`	`SupportedLayouts` The layouts the user can switch between, mapping each supported layout type to view settings applied when switching to it (or `true` for defaults). Only picker layouts (`pickerGrid`, `pickerTable`, `pickerActivity`) are supported; other layout types are ignored.
`selection` Required		`string[]` The currently selected items, as a list of item ids. Selection is always controlled in pickers, so this prop is required.
`onChangeSelection` Required		`(items: string[]) => void` Callback invoked with the new list of selected item ids whenever the selection changes.
`children`		`ReactNode` Custom component tree rendered instead of the default layout composition, using the internal `DataViewsPicker.*` sub-components.
`config`	`{ perPageSizes: [ 10, 20, 50, 100 ] }`	`{ perPageSizes: number[]; mediaFitControl?: boolean \| undefined; }` Static configuration of the component’s UI.
`itemListLabel`		`string` The accessible label for the list of items rendered by the layout.
`empty`		`ReactNode` Content rendered when the dataset is empty (no items match the current view).
`onReset`		`false \| (() => void) \| undefined` Callback to reset the view to its initial state, wired to the “Reset view” button in the view options popover. When provided, the view options toggle also shows a “modified” indicator. Pass `false` to render the button disabled (the view is not modified); omit the prop to hide the button altogether (no reset support).
`getItemId` Required	`( item: ItemWithId ) => item.id`	`(item: SpaceObject) => string` Returns a unique id for an item. Required when items have no string `id` property.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = ( {
	perPageSizes = [ 10, 25, 50, 100 ],
	isMultiselectable,
	isGrouped,
	infiniteScrollEnabled,
	mediaFit,
	mediaFitControl,
}: {
	perPageSizes: number[];
	isMultiselectable: boolean;
	isGrouped: boolean;
	infiniteScrollEnabled: boolean;
	mediaFit?: MediaFit;
	mediaFitControl?: boolean;
} ) => (
	<DataViewsPickerContent
		perPageSizes={ perPageSizes }
		isMultiselectable={ isMultiselectable }
		isGrouped={ isGrouped }
		infiniteScrollEnabled={ infiniteScrollEnabled }
		mediaFit={ mediaFit }
		mediaFitControl={ mediaFitControl }
	/>
);

const WithModal = ( {
	perPageSizes = [ 10, 25, 50, 100 ],
	isMultiselectable,
	isGrouped,
	infiniteScrollEnabled,
	mediaFit,
	mediaFitControl,
}: {
	perPageSizes: number[];
	isMultiselectable: boolean;
	isGrouped: boolean;
	infiniteScrollEnabled: boolean;
	mediaFit?: MediaFit;
	mediaFitControl?: boolean;
} ) => {
	const [ isModalOpen, setIsModalOpen ] = useState( false );
	const [ selectedItems, setSelectedItems ] = useState< SpaceObject[] >( [] );

	const modalActions: ActionButton< SpaceObject >[] = [
		{
			id: 'cancel',
			label: 'Cancel',
			supportsBulk: isMultiselectable,
			callback() {
				setIsModalOpen( false );
			},
		},
		{
			id: 'confirm',
			label: 'Confirm',
			isPrimary: true,
			supportsBulk: isMultiselectable,
			callback( items ) {
				setSelectedItems( items );
				setIsModalOpen( false );
			},
		},
	];

	return (
		<>
			<Stack direction="row" justify="left" gap="sm">
				<Button
					variant="primary"
					__next40pxDefaultSize
					onClick={ () => setIsModalOpen( true ) }
				>
					Open Picker Modal
				</Button>
				<Button
					onClick={ () => setSelectedItems( [] ) }
					disabled={ ! selectedItems.length }
					accessibleWhenDisabled
					__next40pxDefaultSize
				>
					Clear Selection
				</Button>
			</Stack>
			{ selectedItems.length > 0 && (
				<p>
					Selected:{ ' ' }
					{ selectedItems
						.map( ( item ) => item.name.title )
						.join( ', ' ) }
				</p>
			) }
			{ isModalOpen && (
				<>
					<style>{ `
						.components-modal__content {
							padding: 0;
						}
						.components-modal__frame.is-full-screen .components-modal__content {
							margin-bottom: 0;
						}
					` }</style>
					<Modal
						title="Select Items"
						onRequestClose={ () => setIsModalOpen( false ) }
						isFullScreen={ false }
						size="fill"
					>
						<DataViewsPickerContent
							perPageSizes={ perPageSizes }
							isMultiselectable={ isMultiselectable }
							isGrouped={ isGrouped }
							infiniteScrollEnabled={ infiniteScrollEnabled }
							mediaFit={ mediaFit }
							mediaFitControl={ mediaFitControl }
							actions={ modalActions }
							selection={ selectedItems.map( ( item ) =>
								String( item.id )
							) }
						/>
					</Modal>
				</>
			) }
		</>
	);
};