useFilter

useFilter returns the filter items (current values and options).

import { useFilter } from '@sajari/react-hooks';

import { useFilter } from '@sajari/react-hooks';

Usage

Editable Example

Suggestions

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );

  const brandFilter = new FilterBuilder({
    name: 'brand',
    options: {
      Apple: "brand = 'Apple'",
      Samsung: "brand = 'Samsung'",
      Dell: "brand = 'Dell'",
      HP: "brand = 'HP'",
      Garmin: "brand = 'Garmin'",
    },
    multi: true,
  });

  const priceFilter = new FilterBuilder({
    name: 'price',
    options: {
      High: 'price >= 200',
      Mid: 'price >= 50',
      Low: 'price < 50',
    },
    multi: false,
    initial: ['High'],
  });

  const FilterRender = React.memo(({ name, title }) => {
    const { multi, options, selected, setSelected, reset } = useFilter(name);

    if (options.length === 0) {
      return null;
    }

    const Group = multi ? CheckboxGroup : RadioGroup;
    const Control = multi ? Checkbox : Radio;

    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            {title}
          </Heading>
          {selected.length > 0 && multi ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={reset}
            >
              Reset
            </button>
          ) : null}
        </div>
        <Group name={name} value={selected} onChange={multi ? setSelected : (e) => setSelected([e.target.value])}>
          {options.map(({ value, label, count }) => (
            <div className="flex justify-between items-center" key={label + count}>
              <Control value={label} checked={selected.includes(label)} onChange={() => {}} fontSize="sm">
                {label}
              </Control>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </Group>
      </div>
    );
  });

  const BrandFilter = () => <FilterRender name="brand" title="Brand" />;
  const PriceFilter = () => <FilterRender name="price" title="Price (bucket)" />;

  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();

    return (
      <div className="flex flex-col space-y-6">
        <Input />

        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r space-y-6">
            {results && (
              <>
                <BrandFilter />
                <PriceFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });

  return (
    <SearchProvider
      search={{
        pipeline,
        fields: new FieldDictionary({
          title: 'name',
          subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
        }),
        filters: [priceFilter, brandFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );
  const brandFilter = new FilterBuilder({
    name: 'brand',
    options: {
      Apple: "brand = 'Apple'",
      Samsung: "brand = 'Samsung'",
      Dell: "brand = 'Dell'",
      HP: "brand = 'HP'",
      Garmin: "brand = 'Garmin'",
    },
    multi: true,
  });
  const priceFilter = new FilterBuilder({
    name: 'price',
    options: {
      High: 'price >= 200',
      Mid: 'price >= 50',
      Low: 'price < 50',
    },
    multi: false,
    initial: ['High'],
  });
  const FilterRender = React.memo(({ name, title }) => {
    const { multi, options, selected, setSelected, reset } = useFilter(name);
    if (options.length === 0) {
      return null;
    }
    const Group = multi ? CheckboxGroup : RadioGroup;
    const Control = multi ? Checkbox : Radio;
    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            {title}
          </Heading>
          {selected.length > 0 && multi ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={reset}
            >
              Reset
            </button>
          ) : null}
        </div>
        <Group name={name} value={selected} onChange={multi ? setSelected : (e) => setSelected([e.target.value])}>
          {options.map(({ value, label, count }) => (
            <div className="flex justify-between items-center" key={label + count}>
              <Control value={label} checked={selected.includes(label)} onChange={() => {}} fontSize="sm">
                {label}
              </Control>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </Group>
      </div>
    );
  });
  const BrandFilter = () => <FilterRender name="brand" title="Brand" />;
  const PriceFilter = () => <FilterRender name="price" title="Price (bucket)" />;
  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();
    return (
      <div className="flex flex-col space-y-6">
        <Input />
        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r space-y-6">
            {results && (
              <>
                <BrandFilter />
                <PriceFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });
  return (
    <SearchProvider
      search={{
        pipeline,
        fields: new FieldDictionary({
          title: 'name',
          subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
        }),
        filters: [priceFilter, brandFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

Count aggregate

Return count aggregate values for a given facet and display them for your users.

Editable Example

Suggestions

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );

  const categoryFilter = new FilterBuilder({
    name: 'category',
    field: 'level1',
    count: true,
    multi: true,
  });

  const priceRangeFilter = new FilterBuilder({
    name: 'priceRange',
    count: true,
    field: 'price_range',
    multi: true,
  });

  const FilterRender = React.memo(({ name, title }) => {
    const { multi, options, selected, setSelected } = useFilter(name);

    if (options.length === 0) {
      return null;
    }

    const Group = multi ? CheckboxGroup : RadioGroup;
    const Control = multi ? Checkbox : Radio;

    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            {title}
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>
        <Group
          name={name}
          value={selected}
          onChange={(values) => setSelected(Array.isArray(values) ? values : [values])}
        >
          {options.map(({ value, label, count }) => (
            <div className="flex justify-between items-center" key={label + count}>
              <Control value={label} checked={selected.includes(label)} onChange={() => {}} fontSize="sm">
                {label}
              </Control>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </Group>
      </div>
    );
  });

  const CategogryFilter = () => <FilterRender name="category" title="Category" />;
  const PriceRangeFilter = () => <FilterRender name="priceRange" title="Range ($)" />;

  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();

    return (
      <div className="flex flex-col space-y-6">
        <Input />

        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r space-y-6">
            {results && (
              <>
                <CategogryFilter />
                <PriceRangeFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });

  return (
    <SearchProvider
      search={{
        pipeline,
        filters: [priceRangeFilter, categoryFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );
  const categoryFilter = new FilterBuilder({
    name: 'category',
    field: 'level1',
    count: true,
    multi: true,
  });
  const priceRangeFilter = new FilterBuilder({
    name: 'priceRange',
    count: true,
    field: 'price_range',
    multi: true,
  });
  const FilterRender = React.memo(({ name, title }) => {
    const { multi, options, selected, setSelected } = useFilter(name);
    if (options.length === 0) {
      return null;
    }
    const Group = multi ? CheckboxGroup : RadioGroup;
    const Control = multi ? Checkbox : Radio;
    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            {title}
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>
        <Group
          name={name}
          value={selected}
          onChange={(values) => setSelected(Array.isArray(values) ? values : [values])}
        >
          {options.map(({ value, label, count }) => (
            <div className="flex justify-between items-center" key={label + count}>
              <Control value={label} checked={selected.includes(label)} onChange={() => {}} fontSize="sm">
                {label}
              </Control>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </Group>
      </div>
    );
  });
  const CategogryFilter = () => <FilterRender name="category" title="Category" />;
  const PriceRangeFilter = () => <FilterRender name="priceRange" title="Range ($)" />;
  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();
    return (
      <div className="flex flex-col space-y-6">
        <Input />
        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r space-y-6">
            {results && (
              <>
                <CategogryFilter />
                <PriceRangeFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });
  return (
    <SearchProvider
      search={{
        pipeline,
        filters: [priceRangeFilter, categoryFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

Customizable

Output from useFilter can be used to customize different interfaces.

Editable Example

Suggestions

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );

  const colorFilter = new FilterBuilder({
    name: 'color',
    field: 'imageTags',
    array: true,
  });

  const ratingFilter = new FilterBuilder({
    name: 'rating',
    field: 'rating',
  });

  const RatingFilter = () => {
    const { multi, options, selected, setSelected } = useFilter('rating');

    if (options.length === 0) {
      return null;
    }

    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            Rating
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>
        <CheckboxGroup name="rating" value={selected} onChange={setSelected}>
          {options.map(({ value, label, count }) => (
            <div className="flex items-center justify-between" key={label + count}>
              <Checkbox value={label} checked={selected.includes(label)} onChange={() => {}}>
                <Rating value={label} />
              </Checkbox>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </CheckboxGroup>
      </div>
    );
  };

  const ColorFilter = () => {
    const { multi, options, selected, setSelected } = useFilter('color');
    const optionKeys = options.map((o) => o.label);

    const validColors = [
      'White',
      'Silver',
      'Black',
      'Pink',
      'Magenta',
      'Red',
      'Beige',
      'Orange',
      'Brown',
      'Yellow',
      'Green',
      'Azure',
      'Aqua',
      'Teal',
      'Turquoise',
      'Blue',
      'ElectricBlue',
      'Lilac',
      'Purple',
      'Violet',
    ].filter((c) => optionKeys.some((o) => o.includes(c)));

    if (validColors.length === 0) {
      return null;
    }

    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            Color
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>

        <Swatch checkedColors={selected} onChange={setSelected}>
          {validColors.map((color) => {
            const Component = Swatch.Color[color];
            return <Component key={color} />;
          })}
        </Swatch>
      </div>
    );
  };

  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();

    return (
      <div className="flex flex-col space-y-6">
        <Input />

        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r">
            {results && (
              <>
                <RatingFilter />
                <ColorFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });

  return (
    <SearchProvider
      search={{
        pipeline,
        fields: new FieldDictionary({
          title: 'name',
          subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
        }),
        filters: [colorFilter, ratingFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

function Example() {
  const pipeline = new Pipeline(
    {
      account: '1594153711901724220',
      collection: 'bestbuy',
    },
    'query',
  );
  const colorFilter = new FilterBuilder({
    name: 'color',
    field: 'imageTags',
    array: true,
  });
  const ratingFilter = new FilterBuilder({
    name: 'rating',
    field: 'rating',
  });
  const RatingFilter = () => {
    const { multi, options, selected, setSelected } = useFilter('rating');
    if (options.length === 0) {
      return null;
    }
    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            Rating
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>
        <CheckboxGroup name="rating" value={selected} onChange={setSelected}>
          {options.map(({ value, label, count }) => (
            <div className="flex items-center justify-between" key={label + count}>
              <Checkbox value={label} checked={selected.includes(label)} onChange={() => {}}>
                <Rating value={label} />
              </Checkbox>
              <span className="ml-2 text-xs text-gray-400">{count}</span>
            </div>
          ))}
        </CheckboxGroup>
      </div>
    );
  };
  const ColorFilter = () => {
    const { multi, options, selected, setSelected } = useFilter('color');
    const optionKeys = options.map((o) => o.label);
    const validColors = [
      'White',
      'Silver',
      'Black',
      'Pink',
      'Magenta',
      'Red',
      'Beige',
      'Orange',
      'Brown',
      'Yellow',
      'Green',
      'Azure',
      'Aqua',
      'Teal',
      'Turquoise',
      'Blue',
      'ElectricBlue',
      'Lilac',
      'Purple',
      'Violet',
    ].filter((c) => optionKeys.some((o) => o.includes(c)));
    if (validColors.length === 0) {
      return null;
    }
    return (
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <Heading as="h6" className="font-medium tracking-wide text-gray-400 uppercase">
            Color
          </Heading>
          {selected.length > 0 ? (
            <button
              className="text-xs text-blue-500 hover:underline uppercase p-0 bg-transparent focus:outline-none"
              onClick={() => setSelected([])}
            >
              Reset
            </button>
          ) : null}
        </div>
        <Swatch checkedColors={selected} onChange={setSelected}>
          {validColors.map((color) => {
            const Component = Swatch.Color[color];
            return <Component key={color} />;
          })}
        </Swatch>
      </div>
    );
  };
  const SearchPlayground = React.memo(() => {
    const { results } = useSearch();
    return (
      <div className="flex flex-col space-y-6">
        <Input />
        <div className="flex -mx-3">
          <div className="w-1/4 px-3 border-gray-100 border-r">
            {results && (
              <>
                <RatingFilter />
                <ColorFilter />
              </>
            )}
          </div>
          <div className="w-3/4 px-3">
            <Results />
          </div>
        </div>
      </div>
    );
  });
  return (
    <SearchProvider
      search={{
        pipeline,
        fields: new FieldDictionary({
          title: 'name',
          subtitle: (data) => data.level4 || data.level3 || data.level2 || data.level1 || data.brand,
        }),
        filters: [colorFilter, ratingFilter],
      }}
    >
      <SearchPlayground />
    </SearchProvider>
  );
}

Anatomy

useFilter returns an object containing the following properties:

Name	Type	Description
`options`	`Option[]`	An array of selectable options
`selected`	`string[]`	An array of, or single item for current selected option(s)
`setSelected`	`(values:string) => void`	Set the selected option(s)
`multi`	`boolean`	Whether the filter allows multiple selections
`reset`	`() => void`	Reset the current state to the initial state

Parameters

useFilter(name, params);

useFilter(name, params);

Name	Type	Default	Description
`name`	`string`		The name of the filter that you specified in `FilterBuilder`.
`params`	`object`		Additional options. See details on the below table.

params

Name	Type	Default	Description
`sort`	`'alpha'` \| `'count'` \| `'none'`	`'alpha'`	`'alpha'` stands for `'alphanumeric'` meaning to sort the items based on label alphabetically, `'count'` to sort based on count, `'none'` to skip the sorting process.
`sortAscending`	`boolean`		Sort the records in descending order.
`includes`	`string[]`		If the list is set, select the items of the list from the filter options.
`excludes`	`string[]`		If the list is set, eliminate the items of the list from the filter options.
`prefixFilter`	`string`		Only include the filter options that starts with the prefix.