useFilter

Introduction

useFilter provides functions for filtering or searching based on substring matches. The builtin JavaScript string methods startsWith, endsWith, and includes could be used for this, but do not implement locale sensitive matching. useFilter provides options to allow ignoring case, diacritics, and Unicode normalization forms, which are implemented according to locale-specific rules. It automatically uses the current locale set by the application, either via the default browser language or via the I18nProvider.

API

useFilter(options?: Intl.CollatorOptions): Filter

Interface

`startsWith(string: string, substring: string): boolean`
Returns whether a string starts with a given substring.
`endsWith(string: string, substring: string): boolean`
Returns whether a string ends with a given substring.
`contains(string: string, substring: string): boolean`
Returns whether a string contains a given substring.

Example

The following example implements a filterable list using a contains matching strategy that ignores both case and diacritics.

Filter:

Wolfgang Amadeus Mozart
Johann Sebastian Bach
Ludwig van Beethoven
Claude Debussy
George Frideric Handel
Frédéric Chopin
Johannes Brahms
Pyotr Ilyich Tchaikovsky
Antonín Dvořák
Felix Mendelssohn
Béla Bartók
Niccolò Paganini

import React from 'react';
import {useFilter} from '@react-aria/i18n';

function Example() {
  const composers = [
    'Wolfgang Amadeus Mozart',
    'Johann Sebastian Bach',
    'Ludwig van Beethoven',
    'Claude Debussy',
    'George Frideric Handel',
    'Frédéric Chopin',
    'Johannes Brahms',
    'Pyotr Ilyich Tchaikovsky',
    'Antonín Dvořák',
    'Felix Mendelssohn',
    'Béla Bartók',
    'Niccolò Paganini'
  ];

  let {contains} = useFilter({
    sensitivity: 'base'
  });

  let [value, setValue] = React.useState('');
  let matchedComposers = composers.filter(composer => contains(composer, value));

  return (
    <>
      <label htmlFor="search-input">Filter: </label>
      <input type="search" id="search-input" value={value} onChange={e => setValue(e.target.value)} />
      <ul style={{height: 300}}>
        {matchedComposers.map((composer, i) =>
          <li key={i}>{composer}</li>)
        }
      </ul>
    </>
  );
}