## 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