Filter Button

Filter Button is a component with an inline label and highlighted value. It lets users choose one or more items from an options menu.

Use a Filter Button to offer a list of choices where multiple selection is possible.

Example

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
    />
  );
}

Result

Variants

Anchor Size

The anchor is available in two sizes: small and medium can be accessed using size prop.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        size="small"
      />
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        size="medium"
      />
    </div>
  );
}

Result

Custom Sorting

You can use sortPredicate property to have custom sorting on the results when typing your query. In this example when searching for 'us' or 'ru', unlike the default sorting, 'United States (US)' or 'Russia (RU)' will appear first, respectively.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'Cyprus (CY)',
      value: 'cyprus'
    },
    {
      label: 'United States (US)',
      value: 'united_states'
    },
    {
      label: 'United Kingdom (UK)',
      value: 'united_kingdom'
    },
    {
      label: 'Belgium (BE)',
      value: 'belgium'
    },
    {
      label: 'Germany (DE)',
      value: 'germany'
    },
    {
      label: 'Russia (RU)',
      value: 'russia'
    },
    {
      label: 'Belarus (BY)',
      value: 'belarus'
    },
    {
      label: 'Italy (IT)',
      value: 'italy'
    },
    {
      label: 'China (CN)',
      value: 'china'
    },
    {
      label: 'France (FR)',
      value: 'france'
    }
  ];

  const [selectedItems, setSelectedItems] = useState([]);

  return (
    <FilterButton
      showResetButton
      name="Countries"
      items={items}
      sortPredicate={(a, b, searchValue) => {
        const abbrRegex = new RegExp(`\\b${searchValue}\\b`, 'gi');
        return (
          Number(abbrRegex.test(b.label)) - Number(abbrRegex.test(a.label))
        );
      }}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
    />
  );
}

Result

Custom Controls

You have Search input and SelectAll checkbox shown by default, which can be hidden using showSearch and showSelectAll props.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      showSearch={false}
      showSelectAll={false}
    />
  );
}

Result

Default Items

You can provide default items which will be used to populate filter once user clicks reset. If not specified filter with multiple selection will reset all items and with single selction filter will reset to initially selected item

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'kiwi',
      value: 'kiwi'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'dragon fruit',
      value: 'dragon fruit'
    },
    {
      label: 'plum',
      value: 'plum'
    },
    {
      label: 'tangerine',
      value: 'tangerine'
    },
    {
      label: 'durian',
      value: 'durian'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'mango',
      value: 'mango'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const defaultItems = [
    {
      label: 'mango',
      value: 'mango'
    }
  ];

  const [multipleSelectedItems, setMultipleSelectedItems] =
    useState(initialSelectedItems);
  const [singleSelectedItems, setSingleSelectedItems] =
    useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        showResetButton
        name="Multiple fruits"
        items={items}
        defaultItems={defaultItems}
        selectedItems={multipleSelectedItems}
        onApply={setMultipleSelectedItems}
      />
      <FilterButton
        showResetButton
        multiple={false}
        name="Single fruit"
        items={items}
        defaultItems={defaultItems}
        selectedItems={singleSelectedItems}
        onApply={setSingleSelectedItems}
      />
    </div>
  );
}

Result

Disabled

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      disabled
    />
  );
}

Result

disableSort

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      disableSort
    />
  );
}

Result

disableSort - Custom Sorting with disabled default sorting

Here is an example of using custom sorting when defaut sorting is disabled.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'Cyprus (CY)',
      value: 'cyprus'
    },
    {
      label: 'United States (US)',
      value: 'united_states'
    },
    {
      label: 'United Kingdom (UK)',
      value: 'united_kingdom'
    },
    {
      label: 'Belgium (BE)',
      value: 'belgium'
    },
    {
      label: 'Germany (DE)',
      value: 'germany'
    },
    {
      label: 'Russia (RU)',
      value: 'russia'
    },
    {
      label: 'Belarus (BY)',
      value: 'belarus'
    },
    {
      label: 'Italy (IT)',
      value: 'italy'
    },
    {
      label: 'China (CN)',
      value: 'china'
    },
    {
      label: 'France (FR)',
      value: 'france'
    }
  ];

  const [selectedItems, setSelectedItems] = useState([]);

  return (
    <FilterButton
      showResetButton
      name="Countries"
      items={items}
      sortPredicate={(a, b, searchValue) => {
        const abbrRegex = new RegExp(`\\b${searchValue}\\b`, 'gi');
        return (
          Number(abbrRegex.test(b.label)) - Number(abbrRegex.test(a.label))
        );
      }}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      disableSort
    />
  );
}

Result

Disable Sort when less items

Sorting is disabled by default when there are less than 6 items. This does not apply to search results.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'pineapple',
      value: 'pineapple'
    },
    {
      label: 'cherry',
      value: 'cherry'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
      />
    </>
  );
}

Result

disableSelectedSort

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'grapes',
      value: 'grapes'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'pineapple',
      value: 'pineapple'
    },
    {
      label: 'cherry',
      value: 'cherry'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        disableSelectedSort
      />
    </>
  );
}

Result

Enable Zero Selection

To have no filters applied, you can enable the prop enableZeroSelection to true.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      enableZeroSelection
    />
  );
}

Result

Footer Warning Message

You can use this prop to display a warning message in the footer. Important note: footerWarningMessage prop and the Reset Button cannot be used at the same time.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        footerWarningMessage="Select a maximum of 6 apps."
      />
    </div>
  );
}

Result

isApplyButtonDisabled

You can use this prop to disable the Apply button.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        isApplyButtonDisabled={true}
      />
    </div>
  );
}

Result

isGroupLabel

You can use this prop to add a Group Label.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'Fruits',
      value: 'fruits',
      isGroupLabel: true
    },
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    },
    {
      label: 'Vegetables',
      value: 'vegetables',
      isGroupLabel: true
    },
    {
      label: 'Beans',
      value: 'beans'
    },
    {
      label: 'Potato',
      value: 'potato'
    },
    {
      label: 'Onion',
      value: 'onion'
    },
    {
      label: 'Spinach',
      value: 'spinach'
    },
    {
      label: 'Tomato',
      value: 'tomato'
    },
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'Spinach',
      value: 'spinach'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        disableSelectedSort
      />
    </div>
  );
}

Result

Loading State

You can use a isLoading property in order to display the loading indicator.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      isLoading
    />
  );
}

Result

Loading More Data

The component supports virtual infinite loading by adding following props:

onLoadMoreData a callback function to load more data.
hasMoreData
isLoadingMoreData
loadingMoreDataLabel custom label of status indicator.

To integrate virtual infinite loading with React Query please refer to useInfiniteQuery hook and this example.

Live Editor

function MyFilterButton() {

  const generateMoreData = useCallback(
    (offset = 0, chunkSize = 25) =>
      Array.from({ length: chunkSize }, (_, index) => {
        const id = offset + index + 1;

        return {
          label: `Label ${id}`,
          value: `value_${id}`,
        };
      }),
    []
  );

  const maxNumberOrRows = 100;
  const initialData = useMemo(() => generateMoreData(), [generateMoreData]);
  const [items, setItems] = useState(initialData);
  const [selectedItems, setSelectedItems] = useState(initialData);
  const [isLoadingMoreData, setIsLoadingMoreData] = useState(false);

  const onLoadMoreData = useCallback(() => {
    setIsLoadingMoreData(true);
    setTimeout(() => {
      const generatedData = generateMoreData(items.length);
      setItems((preItems) => [...preItems, ...generatedData]);
      setSelectedItems((selectedItems) => [...selectedItems, ...generatedData]);
      setIsLoadingMoreData(false);
    }, 3000);
  }, [items.length, generateMoreData]);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      hasMoreData={items.length < maxNumberOrRows}
      isLoadingMoreData={isLoadingMoreData}
      onLoadMoreData={onLoadMoreData}
    />
  );
}

Result

onSelectionChange

The onSelectionChange prop is an onChange callback. You can use this prop to send information about the selected items to the parent component.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
  const [message, setMessage] = useState('');
  const [isDisabled, setIsDisabled] = useState(false);



  const onSelectionChange = (items) => {
    if(items.length > 6) {
      setMessage('Select a maximum of 6 apps.');
      setIsDisabled(true);
    }
    else {
      setMessage('');
      setIsDisabled(false);
    }
  }
  
  const renderValue = () => {
    return (
      <div style={{ display: 'flex', alignItems: 'center' }}>
        <Icon name="Pin" css={{ marginRight: Spacing10 }} />
        <span>Pin apps</span>
      </div>
    );
  };

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      onSelectionChange={onSelectionChange}
      footerWarningMessage={message}
      renderValue={renderValue}
      isApplyButtonDisabled={isDisabled}
    />
  );
}

Result

Render Items

You can use a renderItem property to define custom render function for filter items.

info

The filter uses the virtualization so if you are about to change the height of items do not forget to specify an itemSize property.

Live Editor

function MyFilterButton() {
  const apps = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  const renderItem = ({ label, appId }) => (
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        width: '100%'
      }}
    >
      <span style={{ flex: 1, textAlign: 'left' }}>{label}</span>
      <Icon
        size="small"
        name="PlatformAndroidFilled"
        css={{ marginLeft: Spacing10 }}
      />
    </div>
  );

  return (
    <FilterButton
      name="Fruits"
      items={apps}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      renderItem={renderItem}
      itemSize={48}
    />
  );
}

Result

Custom List Component

You can use a customList property to define custom component for filter items.

info

Utilize this property to customize the component of the specific filter items. Please keep in mind that you will be responsible for managing styles and keyboard navigation if you opt to pass a custom component. This functionality is most effectively employed in conjunction with the FilterButtonContext context.

Live Editor

function MyFilterButton() {
  const CustomListComponent = ({
    label,
    value,
    checked,
    onClick,
    onKeyDown
  }) => {
    const context = useContext(FilterButtonContext);
    // Get all values from context
    const {
      setSelectedItems,
      selectedItems,
      setSearchValue,
      setAreCheckedItemsChanged
    } = context;

    console.log({ selectedItems });

    return (
      <div style={{ paddingLeft: '10px' }}>
        <Switch
          checked={checked}
          size="small"
          label={label}
          labelPosition="right"
          onChange={onClick}
          onKeyDown={onKeyDown}
        />
      </div>
    );
  };

  const apps = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const [initialValues, setInitialValues] = useState(initialSelectedItems);

  return (
    <FilterButton
      name="Fruits"
      items={apps}
      selectedItems={initialValues}
      onApply={setInitialValues}
      customList={CustomListComponent}
      itemSize={48}
    />
  );
}

Result

InfoText

A text value to show information related to the selection.

You can change the position of the info text to be on top of the FilterButton as well.

warning

Please avoid using the Info Text on top of the FilterButton when you also need the optional label.

warning

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      infoText='Sample info Text'
    />
  );
}

Result

We also support text tags inside the Info Text. Like strong, b, i and a.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);
  const infoText = `Info <b>text</b> really <i>long</i> that <a href='#'> goes </a> on to a <strong> second </strong>line`;

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      infoText={infoText}
    />
  );
}

Result

Invalid State

A user can set a invalid state when the selection is improper.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      infoText={'I am sample invalid infoText'}
      invalid
    />
  );
}

Result

Mode Shifter

In FilterButton we have a mode shifter which can be enabled when modeShifter is true and onModeChange handler is provided. We have 2 mode include and exclude, which can be controlled using onModeChange handler which uses an argument of either of 2 modes.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);
  const [modeType, setModeType] = useState('include');
  const onModeChange = (value) => {
    setModeType(value);
  };

  const onApplyToFilter = (selectedItems, mode) => {
    console.log(selectedItems, mode);
    setSelectedItems(selectedItems);
  };

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={onApplyToFilter}
      showResetButton
      modeShifter
      modeType={modeType}
      onModeChange={onModeChange}
    />
  );
}

Result

You can also change the Mode labels using the modeLabels property.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);
  const [modeType, setModeType] = useState('include');
  const onModeChange = (value) => {
    setModeType(value);
  };

  const modeLabels = {
    include: 'enthalten',
    exclude: 'ausschließen'
  };

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      modeShifter
      modeType={modeType}
      onModeChange={onModeChange}
      modeLabels={modeLabels}
    />
  );
}

Result

RenderValue

You can use a renderValue property to define custom render function for the filter value. When specified this function is used to render a custom element within the trigger.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  const renderValue = () => {
    return (
      <div style={{ display: 'flex', alignItems: 'center' }}>
        <Icon name="CogWheel" css={{ marginRight: Spacing10 }} />
        <span>All fruits</span>
        <Badge
          color="negative"
          label="Custom label"
          css={{ marginLeft: Spacing10 }}
        />
      </div>
    );
  };

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      renderValue={renderValue}
    />
  );
}

Result

Reset Button

You can use a showResetButton property in order to display the reset button. The reset button selects all option items.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
    />
  );
}

Result

The menu list is available in three sizes: small, medium and large can be accessed using menuSize prop. It is ignored if isFullWidthTrigger is true. In this case the menu takes the same width as the trigger.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <div style={{ display: 'flex', gap: Spacing10 }}>
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        menuSize="small"
      />
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        menuSize="medium"
      />
      <FilterButton
        name="Fruits"
        items={items}
        selectedItems={selectedItems}
        onApply={setSelectedItems}
        menuSize="large"
      />
    </div>
  );
}

Result

Single Value Selection

You can use multiple property to define if you want to have multiple or single selection for defined options.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'kiwi',
      value: 'kiwi'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'dragon fruit',
      value: 'dragon fruit'
    },
    {
      label: 'plum',
      value: 'plum'
    },
    {
      label: 'tangerine',
      value: 'tangerine'
    },
    {
      label: 'durian',
      value: 'durian'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'mango',
      value: 'mango'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  return (
    <FilterButton
      showResetButton
      multiple={false}
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
    />
  );
}

Result

Full width trigger

You can use isFullWidthTrigger property to allow the trigger to take the available width. If isFullWidthTrigger is true the menu takes the same width as the trigger.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(items);

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      showResetButton
      isFullWidthTrigger
    />
  );
}

Result

Translate

You can use a getElementLabel property to define the text for all elements within the Filter. This function will be called with one of the following values as an argument:

  type FilterButtonTextElements =
  | 'apply-button'
  | 'reset-button'
  | 'select-all-default'
  | 'select-all-searched'
  | 'loading-message'
  | 'not-found-message'
  | 'all-selected-badge-label'
  | 'search-input-placeholder'

Each value matches the element within the Filter, e.g. 'apply-button' specifies the label for the Apply button etc.

Live Editor

function MyFilterButton() {
  const items = [
    {
      label: 'apple',
      value: 'apple'
    },
    {
      label: 'banana',
      value: 'banana'
    },
    {
      label: 'orange',
      value: 'orange'
    },
    {
      label: 'cherry',
      value: 'cherry'
    },
    {
      label: 'peach',
      value: 'peach'
    },
    {
      label: 'pear',
      value: 'pear'
    },
    {
      label: 'grapefruit',
      value: 'grapefruit'
    },
    {
      label: 'blackberry',
      value: 'blackberry'
    },
    {
      label: 'strawberry',
      value: 'strawberry'
    },
    {
      label: 'pineapple',
      value: 'pineapple'
    }
  ];

  const initialSelectedItems = [
    {
      label: 'apple',
      value: 'apple'
    }
  ];

  const [selectedItems, setSelectedItems] = useState(initialSelectedItems);

  const getElementLabel = (element) => {
    if (element === 'apply-button') {
      return 'Hello';
    }
    return 'world';
  };

  return (
    <FilterButton
      name="Fruits"
      items={items}
      selectedItems={selectedItems}
      onApply={setSelectedItems}
      getElementLabel={getElementLabel}
    />
  );
}

Result

Props

Name	Type	Default
selectedItems * Array of options that populates the filter button.	T[]	—
items * Array of items that populate the filter button. The item has two required properties of type `string`: value and label. It can be extended with any additional properties.	T[]	—
name * The name of the Filter. It will be used for displaying the value for Select Button	string	—
multiple Use this prop to switch between multiple and single selections	boolean	true
id Native HTML attribute: Link . Internally, this component uses a random id. We use it to associate an input with a label element. As the random id might break snapshot tests it can be overridden by setting an explicit id.	string	—
defaultItems Array of options which will be selected once user will reset selection	T[]	—
disabled Use this prop if the component should not be interactive	boolean	—
infoText Instructions to help users correctly fill in the data	string	—
invalid Visually notify the user that the provided value is invalid	boolean	—
getElementLabel Use this prop to override the default elements texts and labels. `FilterButtonTextElements` contains elements: \| 'apply-button' \| 'reset-button' \| 'select-all-default' \| 'select-all-searched' \| 'loading-message' \| 'not-found-message' \| 'all-selected-badge-label' \| 'search-input-placeholder'	((element: FilterButtonTextElements) => string)	—
isApplyButtonDisabled Use this prop to disable the Apply button regardless of selection state	boolean	—
isLoading Use this prop if the component should display loading indicator.	boolean	—
itemSize The base height of every item within the Filter.	number	32
size The size of the FilterAnchor.	"small" \| "medium"	"small"
menuSize The size of the FilterList.	"small" \| "medium" \| "large"	"small"
showResetButton Use this prop if the component should display the Reset button inside the Filter.	boolean	—
onReset Use this prop to override the default behavior of the handler called when a user clicks on Reset button. Returned items will be the ones selected after handler is applied.	((initialSelectedItems: T[]) => T[])	—
onApply The handler will be called when a user closes the Filter.	((selectedItems: T[], currentModeType?: modeType) => void)	—
onSelectionChange Callback that fires whenever checkbox selections change	((selectedItems: T[]) => void)	—
renderItem Use this prop to override the default rendering function for Filter items.	((item: T) => ReactNode)	—
customList Use this prop to render a custom list component for each Filter items	ComponentType<T>	—
searchPredicate Use this prop to override the default search function. The default function make a local comparing between an item label and a search string.	SearchItemPredicate<T>	—
sortPredicate Use this prop to custom sort filtered options By default options will come in order defined in `useSortedItems` hook	SortPredicate<T>	—
renderValue Use this prop to override the default rendering function for the Filter anchor.	(<T extends FilterItem>(selectedItems: T[]) => ReactNode)	—
aria-label Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link	string	—
aria-labelledby Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link	string	—
zIndex Use this prop if you need to custom z-index for filter content	number	—
showSelectAll Boolean prop showing Select all checkbox	boolean	true
showSearch Boolean prop showing Search input field	boolean	true
disableSort disable sorting	boolean	false
disableSelectedSort disable selected sorting	boolean	false
modeShifter This is a boolean prop to show the mode shifter	boolean	—
modeType This is the modeType to either include or exclude	"include" \| "exclude"	—
modeLabels Label string for modeType	modeLabels	—
onModeChange The handler will be called when a user change the mode.	(() => void)	—
isFullWidthTrigger Allows the trigger to take the available width	boolean	—
enableZeroSelection Boolean for enabling zero items selection	boolean	false
footerWarningMessage Use this prop to provide a warning message in the footer area	string	—
onLoadMoreData This prop is used for Infinite Loading	((startIndex?: number, stopIndex?: number) => void \| Promise<void>) \| undefined	—
isLoadingMoreData This prop is used for Infinite Loading	boolean	—
hasMoreData This prop is used for Infinite Loading	boolean	—
loadingMoreDataLabel This prop is used for Infinite Loading	string	—
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence	string	—
* - the prop is required.

Example​

Variants​

Anchor Size​

Custom Sorting​

Custom Controls​

Default Items​

Disabled​

disableSort​

disableSort - Custom Sorting with disabled default sorting​

Disable Sort when less items​

disableSelectedSort​

Enable Zero Selection​

Footer Warning Message​

isApplyButtonDisabled​

isGroupLabel​

Loading State​

Loading More Data​

onSelectionChange​

Render Items​

Custom List Component​

InfoText​

Invalid State​

Mode Shifter​

RenderValue​

Reset Button​

Menu Size​

Single Value Selection​

Full width trigger​

Translate​

Props​

Example

Variants

Anchor Size

Custom Sorting

Custom Controls

Default Items

Disabled

disableSort

disableSort - Custom Sorting with disabled default sorting

Disable Sort when less items

disableSelectedSort

Enable Zero Selection

Footer Warning Message

isApplyButtonDisabled

isGroupLabel

Loading State

Loading More Data

onSelectionChange

Render Items

Custom List Component

InfoText

Invalid State

Mode Shifter

RenderValue

Reset Button

Menu Size

Single Value Selection

Full width trigger

Translate

Props