Filter

A styled checkbox component for filtering content, with support for dropdown indicators, validation states, and error messages

Category Filter

'use client';

import { Filter } from '@/ui/forms/Filter';
import { Icon } from '@clubmed/trident-icons';

export function FilterDemo() {
  return (
    <Filter checked={false}>
      <div className="flex items-center gap-x-8">
        <Icon name="Filters" />
        Category Filter
      </div>
    </Filter>
  );
}

Installation


npx shadcn@latest add https://develop.trident-ui.pro.clubmed/r/filter.json

Usage

'use client';
 
import { useState } from 'react';
import { Filter } from '@/docs/lib/ui/forms/filter';
 
export function Component() {
  const [filters, setFilters] = useState<Record<string, boolean>>({
    category: false,
  });
 
  const handleFilterChange = (name: string, value: boolean | null) => {
    setFilters((prev) => ({ ...prev, [name]: value !== null }));
  };
 
  return (
    <Filter name="category" checked={filters.category} onChange={handleFilterChange}>
      Category Filter
    </Filter>
  );
}

API Reference

Filter

Prop	Type	Default	Description
`children`	`ReactNode`	`undefined`	The label text or content to display inside the filter button
`checked`	`boolean`	`false`	Whether the filter is currently selected/checked
`hasDropdown`	`boolean`	`undefined`	When true, displays a dropdown arrow icon next to the check icon
`onChange`	`(name: string, value: Value \| null) => void`	`undefined`	Callback function triggered when the filter state changes. Receives the name and new value
`value`	`Value`	`undefined`	The value associated with this filter when checked. Defaults to the checked state if not provided
`name`	`string`	`id`	Name attribute for the underlying checkbox input. Defaults to the `id` prop
`id`	`string`	`auto`	Unique identifier for the filter. Auto-generated using `useId()` if not provided
`disabled`	`boolean`	`false`	When true, prevents user interaction and applies disabled styling
`tabIndex`	`number`	`0`	Controls the tab order for keyboard navigation
`validationStatus`	`"default" \| "error" \| "success"`	`"default"`	Visual state of the filter. Use "error" to display error messages
`errorMessage`	`string`	`undefined`	Error message to display when `validationStatus` is "error" and not disabled
`dataTestId`	`string`	`undefined`	Custom data-testid attribute for testing purposes
`className`	`string`	`undefined`	Additional CSS classes to apply to the outer container div
`label`	`ReactNode`	`undefined`	Optional label element (from FormControlProps, though not commonly used for Filter)
`description`	`string`	`undefined`	Optional description text (from FormLabelProps)
`required`	`boolean`	`undefined`	Marks the filter as required (from FormLabelProps)
`hideRequiredStar`	`boolean`	`undefined`	Hides the required star indicator (from FormLabelProps)
`layout`	`"horizontal" \| "vertical" \| "horizontal-${string}"`	`undefined`	Layout orientation for the label (from FormLabelProps)

The Filter component also supports all standard HTML input attributes via InputHTMLAttributes<HTMLInputElement>.

Notes

Checkbox-based: Filter is built on a native checkbox input, providing proper semantics and keyboard accessibility out of the box
Check icon: When checked, displays a check icon (CheckDefault) to indicate the selected state
Dropdown indicator: Set hasDropdown={true} to show an arrow icon, useful when the filter opens a dropdown menu
Validation states: Supports "default", "error", and "success" states. Error messages are automatically hidden when disabled
Error display: Error messages appear below the filter with an error icon and role="alert" for accessibility
Value handling: The onChange callback receives either the specified value (when checked) or null (when unchecked)
State management: Uses the internal useValue hook to manage checked state and coordinate with the onChange callback
Disabled state: When disabled, prevents clicks and hides error messages. Error state is automatically converted to disabled state internally
Data attributes: Includes data-name="Filter" for styling and data-testid for testing
Keyboard support: Fully keyboard accessible with configurable tabIndex
Client component: This is a client component that requires the "use client" directive due to state management and event handlers

ExpandableCard FormCheckbox

On This Page

Installation Usage API Reference Filter Notes