Skip to main content
Component Location: design-system/components/AxFilterBar

​
Overview

AxFilterBar is a flexible filtering toolbar that combines search input, multiple filter dropdowns, a sort selector, and optional action buttons. Designed for list and table views where users need to refine large datasets.

​
Import

import AxFilterBar from '@/design-system/components/AxFilterBar'
import type { AxFilterBarProps, FilterConfig, SortConfig } from '@/design-system/components/AxFilterBar'

​
Basic Usage

<AxFilterBar
  search={{
    placeholder: "Search medications...",
    value: searchQuery,
    onChange: (e) => setSearchQuery(e.target.value)
  }}
  resultCount={24}
/>

​
With Filters and Sort

const filters: FilterConfig[] = [
  {
    key: "status",
    placeholder: "Status",
    options: [
      { label: "Active", value: "active" },
      { label: "Inactive", value: "inactive" }
    ],
    value: statusFilter,
    onChange: setStatusFilter
  },
  {
    key: "category",
    placeholder: "Category",
    options: categoryOptions,
    multiple: true,
    maxTagCount: 2,
    value: categoryFilter,
    onChange: setCategoryFilter
  }
]

const sort: SortConfig = {
  options: [
    { label: "Name A-Z", value: "name-asc" },
    { label: "Name Z-A", value: "name-desc" },
    { label: "Recently Added", value: "date-desc" }
  ],
  value: sortBy,
  onChange: setSortBy
}

<AxFilterBar
  filters={filters}
  sort={sort}
  resultCount="24 medications"
  extra={<Button type="primary">Add Medication</Button>}
/>

​
Props

​
AxFilterBarProps

​
search
object | false
Search input configuration. Pass false to hide the search input entirely.
​
filters
FilterConfig[]
Array of filter dropdown configurations. See FilterConfig type below.
​
sort
SortConfig
Sort dropdown configuration. See SortConfig type below.
​
resultCount
number | string
Result count displayed below the filter bar. Pass a number for automatic “X results” formatting, or a custom string like “24 medications”.
​
extra
React.ReactNode
Extra content rendered on the right side of the bar (e.g., action buttons, CTAs).
​
className
string
Additional CSS class name for the container.

​
Type Definitions

​
FilterConfig

export type FilterConfig = {
  /** Unique key for the filter */
  key: string
  /** Placeholder text for the select */
  placeholder?: string
  /** Select options */
  options: SelectProps["options"]
  /** Allow multiple selections */
  multiple?: boolean
  /** Max tags to show before "+N more" (default: 1 for multiple) */
  maxTagCount?: number
  /** Width of the select (default: 160px) */
  width?: number | string
  /** Allow clearing the selection */
  allowClear?: boolean
  /** Current value (controlled) */
  value?: SelectProps["value"]
  /** Change handler */
  onChange?: SelectProps["onChange"]
}
​
key
string
required
Unique identifier for this filter. Used as the React key.
​
placeholder
string
Placeholder text shown in the dropdown.
​
options
SelectProps['options']
required
Array of select options. Each option should have label and value properties.
​
multiple
boolean
default:"false"
Enable multi-select mode for this filter.
​
maxTagCount
number
default:"1"
Maximum number of selected tags to display before showing “+N more”. Only applies when multiple={true}.
​
width
number | string
default:"160px"
Width of the select dropdown.
​
allowClear
boolean
default:"true"
Show a clear button to reset the selection.
​
value
any
Controlled value for the filter. Can be a string, number, or array (for multi-select).
​
onChange
(value: any, option: any) => void
Callback fired when the selection changes.

​
SortConfig

export type SortConfig = {
  /** Sort options */
  options: SelectProps["options"]
  /** Current value (controlled) */
  value?: SelectProps["value"]
  /** Change handler */
  onChange?: SelectProps["onChange"]
  /** Width (default: 130px) */
  width?: number | string
  /** Show "Sort by" label (default: true) */
  showLabel?: boolean
}
​
options
SelectProps['options']
required
Array of sort options (e.g., [{ label: "Name A-Z", value: "name-asc" }]).
​
value
any
Controlled value for the sort dropdown.
​
onChange
(value: any, option: any) => void
Callback fired when sort selection changes.
​
width
number | string
default:"130px"
Width of the sort dropdown.
​
showLabel
boolean
default:"true"
Whether to show the “Sort by” label before the dropdown.

​
Examples

​
Filter Bar Without Search

<AxFilterBar
  search={false}
  filters={[
    {
      key: "status",
      placeholder: "All Statuses",
      options: statusOptions,
      value: status,
      onChange: setStatus
    }
  ]}
/>

​
Multi-Select Filter

const categoryFilter: FilterConfig = {
  key: "categories",
  placeholder: "Categories",
  options: [
    { label: "Antibiotics", value: "antibiotics" },
    { label: "Analgesics", value: "analgesics" },
    { label: "Vaccines", value: "vaccines" }
  ],
  multiple: true,
  maxTagCount: 2,
  value: selectedCategories,
  onChange: setSelectedCategories
}

<AxFilterBar filters={[categoryFilter]} />

​
With Custom Result Count

<AxFilterBar
  search={{ placeholder: "Search suppliers..." }}
  resultCount={`${filteredCount} of ${totalCount} suppliers`}
/>

​
With Action Button

<AxFilterBar
  search={{ placeholder: "Search..." }}
  filters={filters}
  sort={sortConfig}
  extra={
    <Button type="primary" icon={<PlusOutlined />}>
      Add New
    </Button>
  }
/>

​
Accessibility

  • Uses semantic <search> element with aria-label="Filter results"
  • Each filter dropdown has appropriate aria-label attributes
  • Sort dropdown uses aria-labelledby when label is visible
  • Result count uses role="status" and aria-live="polite" for screen reader announcements

​
Design Notes

  • Search input appears first (leftmost)
  • Filters and sort are grouped in the middle
  • Extra content (buttons) is always right-aligned
  • Result count renders below the main bar
  • All dropdowns use popupMatchSelectWidth={false} for flexible dropdown widths
  • Default widths: Search (flexible), Filters (160px), Sort (130px)

Build docs developers (and LLMs) love

Get started for freeTalk to us