---
title: "FilterBar"
description: "A filter form inside a search landmark: fields on top and the result with actions (clear, apply) in the bottom bar. Filters should be reflected in the URL."
kind: block
id: C-057
category: erp
registry: "filter-bar"
docs: "https://koten.codehive.com.co/blocks/erp/filter-bar"
markdown: "https://koten.codehive.com.co/md/blocks/erp/filter-bar.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/filter-bar.json"
language: en
---

# FilterBar · 絞り込み

> Block C-057 in the Koten UI catalog.

A filter form inside a search landmark: fields on top and the result with actions (clear, apply) in the bottom bar. Filters should be reflected in the URL.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/filter-bar.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/filter-bar.json
```

## Files

- `@/components/patterns/filter-bar.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Composition

This block composes Koten primitives. Read the source files above before changing its anatomy.

## Examples

### Order filters

Search, submit and clear; the result moves from 132 to 24.

```tsx
<FilterBar
  label="Order filters"
  submitLabel="Apply filters"
  resetLabel="Clear"
  resultLabel="132 orders"
  onSubmit={applyFilters}
  onReset={clearFilters}
>
  <Field label="Search">
    <Input type="search" placeholder="Number, customer or SKU" />
  </Field>
  <Select label="Status" defaultValue="all" items={statusItems} />
  <Select label="Warehouse" defaultValue="all" items={warehouseItems} />
</FilterBar>
```

### A single field

The bar works with one field and the same pair of actions.

```tsx
<FilterBar
  label="Search orders"
  submitLabel="Apply filters"
  resetLabel="Clear"
  resultLabel="132 orders"
  onSubmit={applyFilters}
  onReset={clearFilters}
>
  <Field label="Search">
    <Input type="search" placeholder="Number, customer or SKU" />
  </Field>
</FilterBar>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | `—` | aria-label of the search landmark wrapping the form. |
| `children` | `ReactNode` | `—` | Grid fields; one to four per row depending on width. |
| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | `—` | Called after preventDefault; read the fields or update the URL here. |
| `onReset` | `() => void` | `—` | Clear is type=button, so it never submits the form. |
| `submitLabel` | `string` | `—` | Label of the primary submit button. |
| `resetLabel` | `string` | `—` | Label of the ghost button that clears the filters. |
| `resultLabel` | `ReactNode` | `—` | Count or summary; if it changes live, wrap it in aria-live. |
| `className` | `string` | `—` | Adds to the component's base classes. |

## Accessibility

- The block is a search landmark with aria-label; fields get a visible label through Field or Select.
- Clear is type=button, so it never submits; Enter does submit the filters.
- resultLabel is not announced on its own: if the result changes live, wrap it in aria-live=polite.

## Sources

- Catalog page: https://koten.codehive.com.co/blocks/erp/filter-bar
- Markdown: https://koten.codehive.com.co/md/blocks/erp/filter-bar.md
- Repository: https://github.com/codehive-colombia/koten