## Usage

The `@eds/filtering` package contains useful components to easily implement the [Filtering pattern](/patterns/filtering/) in your application. Alongside the documentation on this page, refer to the pattern for more guidelines and composition examples.

## FilterBar

The `<FilterBar />` component is used to create a consistent layout of the filter controls, that automatically adheres to the [Filtering pattern](/patterns/filtering/). It provides spacing, positioning and responsive stacking, as well as props to show/hide fixed elements.

- Use the `loading` prop to display a loading spinner when filter results are being fetched.
- Pass any quick filter controls, such as [SelectDropdown](/packages/select-dropdown/) or [Toggle](/packages/toggle/) via `children`. Max 3 as per pattern.
- If advanced filtering is needed, pass an [AllFiltersButton](#allfiltersbutton) via `children` as the first element.
- Use the `clearable` prop to display a "Clear" button when any advanced/quick filters are applied, and the `onClear` prop to pass a function that clears all the filters.
- Optionally customize the clear button label using the `clearButtonLabel` prop (defaults to "Clear"). When using the default "Clear" label, the aria-label automatically defaults to "Clear all filters" for better accessibility. For custom labels, use the `clearButtonAriaLabel` prop to provide a descriptive aria-label if needed.

**NOTE:** The following code examples are not fully interactive. Refer to [Filtering pattern examples](/patterns/filtering/examples) for more realistic implementations, fully interactive with state handling and async data fetching.

```tsx live
/** Placeholder data for demo purposes. */
const { headers, data } = placeholderTableData({ columns: 4, rows: 30 });
const allDepartmentOptions = React.useMemo(() => generateSelectItemsFromData(data, 'department'), []);
const allRoleOptions = React.useMemo(() => generateSelectItemsFromData(data, 'role'), []);

/** Filter state example. */
const [departments, setDepartments] = useState<typeof allDepartmentOptions | null>([]);
const [roles, setRoles] = useState<typeof allRoleOptions | null>([]);
const [excludeEngineers, setExcludeEngineers] = useState<boolean>(false);
const [keywordFilter, setKeywordFilter] = useState<string>('');

return (
  <FilterBar
    loading={true}
    clearable={true}
    onClear={() => {
      setExcludeEngineers(false);
      setDepartments([]);
      setRoles([]);
      setKeywordFilter('');
    }}
    keywordFilter={{
      placeholder: 'Search by name...',
      value: keywordFilter,
      onChange: (event) => setKeywordFilter(event.target.value),
      onClear: () => setKeywordFilter(''),
      width: '10rem',
    }}
    clearButtonLabel="Reset filters"
  >
    <SelectDropdown
      searchable
      clearButton
      label="Role"
      value={roles}
      isMulti
      onChangeMulti={setRoles}
      items={allRoleOptions}
    />

    <SelectDropdown
      searchable
      clearButton
      label="Department"
      value={departments}
      isMulti
      onChangeMulti={setDepartments}
      items={allDepartmentOptions}
    />

    <Toggle label="Exclude engineers" size="small" toggled={excludeEngineers} onClick={setExcludeEngineers} />
  </FilterBar>
);
```

### Keyword filter only

When implementing the [keyword filter only](/patterns/filtering/examples/#keyword-filter-only) pattern, the positioning automatically changes to adhere to guidelines.

- Since the keyword filter has its own `onClear` functionality, the filter bar's `clearable` and `onClear` props are redundant for this variant.
- Use the `width` prop to adjust the width of the keyword filter if needed.

```tsx live
const [keywordFilter, setKeywordFilter] = useState('');

return (
  <FilterBar
    loading={true}
    keywordFilter={{
      placeholder: 'Search by name, position, role...',
      value: keywordFilter,
      onChange: (event) => setKeywordFilter(event.target.value),
      onClear: () => setKeywordFilter(''),
      width: '16rem', // optionally set the width if needed
    }}
    clearButtonLabel="Reset"
  />
);
```

## AllFiltersButton

The `<AllFiltersButton />` component is a button made specifically for opening a modal containing all available filters in a view. See an example of "All filters" modal on [Filtering pattern examples](/patterns/filtering/examples/#advanced-filters).

Use the `numberFiltersApplied` prop to pass the number of applied filters. It defaults to `0` and displays in a [NumberBadge](/packages/badge/#numberbadge). The number is capped at 99, so if 100 or more is passed it will say `99+`.

```tsx live
<Flex gap="medium">
  <AllFiltersButton />
  <AllFiltersButton numberFiltersApplied={100} />
</Flex>
```

A set of components to help filter large data sets.

Filtering

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

loading

Optionally pass in quick filter controls, for example SelectDropdown and Toggle.
NOTE: Max 3 quick filters as per Filtering pattern guidelines. Always use `small` size when applicable.

children

Displays a "Clear" button when true.
As per pattern, the button should be visible when any filters are applied.

clearable

Handler for the "Clear" button's onClick event.
This should clear all applied filters incl. keyword filter.

onClear

clearButtonLabel

Aria-label for the clear button.
When not provided and clearButtonLabel is "Clear", defaults to "Clear all filters".
For custom labels, provide this prop if a different aria-label is needed.

clearButtonAriaLabel

Optionally pass an object with search input props to display a keyword filter.
Use `value`, `onChange`, `onClear` to control the input.
Pass a `placeholder`, in the format of `Search by name, role...`,
which will also populate the `aria-label` unless provided.
Size is locked to `small`.

keywordFilter

Function to be triggered following a click event of the button.

onClick

The number of filters applied, renders a NumberBadge. Caps at 99. Defaults to `0`.

Prop	Required	Description	Type
`loading`	✅	Displays a loading spinner when true.	boolean
`children`	—	Optionally pass in quick filter controls, for example SelectDropdown and Toggle. NOTE: Max 3 quick filters as per Filtering pattern guidelines. Always use small size when applicable.	ReactElement<any, string \| JSXElementConstructor<any>> \| [ReactElement<any, string \| JSXElementConstructor<any>>, ReactElement<any, string \| JSXElementConstructor<any>>, ReactElement<...>?]
`clearable`	—	Displays a "Clear" button when true. As per pattern, the button should be visible when any filters are applied.	boolean
`onClear`	—	Handler for the "Clear" button's onClick event. This should clear all applied filters incl. keyword filter.	() => void
`clearButtonLabel`	—	Label for the clear button.	string
`clearButtonAriaLabel`	—	Aria-label for the clear button. When not provided and clearButtonLabel is "Clear", defaults to "Clear all filters". For custom labels, provide this prop if a different aria-label is needed.	string
`keywordFilter`	—	Optionally pass an object with search input props to display a keyword filter. Use value, onChange, onClear to control the input. Pass a placeholder, in the format of Search by name, role..., which will also populate the aria-label unless provided. Size is locked to small.	Omit<SearchInputProps, "size"> & { width?: Width<string \| number>; }

Prop	Required	Description	Type
`onClick`	—	Function to be triggered following a click event of the button.	MouseEventHandler<HTMLButtonElement>
`numberFiltersApplied`	—	The number of filters applied, renders a NumberBadge. Caps at 99. Defaults to 0.	number
`disabled`	—	Prevents user interaction with the button and gives it a disabled style.	boolean
`block`	—	Makes the button fill its container.	false \| trueSupports responsive prop syntax