PowerSearch·component·@astryxdesign/core

Power Search

PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.

Open in Playground @astryxdesign/core/PowerSearch

Showcases and examples

5 documented examples

Power Search

Token-based filter bar with enum and text fields, pre-populated with sample filters.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · power-search-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {PowerSearch} from '@astryxdesign/core/PowerSearch';
import type {
  PowerSearchConfig,
  PowerSearchFilter,
} from '@astryxdesign/core/PowerSearch';

const config: PowerSearchConfig = {
  name: 'BasicSearch',
  fields: [
    {
      key: 'status',
      label: 'Status',
      defaultOperator: 'is',
      operators: [
        {
          key: 'is',
          label: 'is',
          value: {
            type: 'enum',
            values: [
              {value: 'open', label: 'Open'},
              {value: 'in_progress', label: 'In Progress'},
              {value: 'closed', label: 'Closed'},
            ],
          },
        },
      ],
    },
    {
      key: 'title',
      label: 'Title',
      defaultOperator: 'contains',
      operators: [
        {key: 'contains', label: 'contains', value: {type: 'string'}},
      ],
    },
  ],
};

const initialFilters: PowerSearchFilter[] = [
  {field: 'status', operator: 'is', value: {type: 'enum', value: 'open'}},
  {
    field: 'title',
    operator: 'contains',
    value: {type: 'string', value: 'dashboard'},
  },
];

export default function PowerSearchShowcase() {
  const [filters, setFilters] = useState<PowerSearchFilter[]>(initialFilters);

  return (
    <PowerSearch
      style={{width: 400}}
      config={config}
      filters={filters}
      onChange={newFilters => setFilters([...newFilters])}
      placeholder="Search by status, title..."
    />
  );
}

Usage

Define clear, descriptive field names and aliases so users can quickly find the filter they need.
Provide a result count to give users feedback on how their filters affect the data set.
Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.
Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Typed props

Prop	Type and behavior
`config`	`PowerSearchConfig` · required Configuration defining available fields, operators, and their value types.
`filters`	`ReadonlyArray<PowerSearchFilter>` · required Currently active filters.
`onChange`	`(filters: ReadonlyArray<PowerSearchFilter>, changeType: 'add' \| 'edit' \| 'remove', index: number) => void` · required Called when filters change. changeType is 'add', 'edit', or 'remove'. index is the affected filter's position.
`label`	`string` · default 'Search' Accessible label for the search input.
`isLabelHidden`	`boolean` · default true Visually hides the label while keeping it accessible.
`placeholder`	`string` · default 'Search...' Placeholder text shown when no filters are selected.
`hasAutoFocus`	`boolean` · default false Auto-focus the input on mount.
`hasClear`	`boolean` · default true Show a clear-all button for removing all filters.
`isReadOnly`	`boolean` · default false Prevent adding, editing, or removing filters.
`isDisabled`	`boolean` · default false Disables the entire component.
`disabledMessage`	`string` Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
`status`	`{type: 'warning' \| 'error' \| 'success', message?: string}` Validation status object with type and optional message.
`startIcon`	`ReactNode \| IconType` Icon to display at the start of the input, before any filter tokens. Forwarded to the internal Tokenizer. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly. Slot: Icon
`statusVariant`	`'attached' \| 'detached'` · default 'attached' How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.
`maxTokenLength`	`number` · default 40 Max character length for filter value display in tokens.
`maxOperatorMenuItems`	`number` · default 10 Maximum suggestions shown in string and entity value typeaheads. Does not affect the main field search menu or enum value menus.
`maxSearchResults`	`number` · default 10 Max ranked results for a non-empty query. Does not affect a field value editor. Browsing with an empty query shows up to 1,000 fields.
`menuWidth`	`number` Width in pixels for the main field/search menu. Does not affect field value editors.
`popoverSaveButtonLabel`	`string` · default 'Apply' Label for the save button in the edit popover.
`timezoneID`	`string` Timezone ID for date formatting (e.g. "America/New_York").
`handleRef`	`Ref<PowerSearchHandle>` Imperative handle with focusTypeahead() and blurTypeahead() methods.
`endContent`	`ReactNode` Content to display at the end of the input row. Useful for action buttons or other controls. Slot: Icon, Badge
`resultCount`	`number \| string` Number of results matching the current filters. When a number, formatted as "N results". When a string, displayed as-is. Changes are announced to screen readers via a polite live region.
`size`	`'sm' \| 'md' \| 'lg'` · default 'md' Size of the search input and tokens.
`menuWidth`	`number` Maximum width for the operator/value dropdown menu in pixels.
`maxOperatorMenuItems`	`number` Maximum number of items displayed in the operator dropdown.
`tokenOverflowBehavior`	`'none' \| 'unfocusedInline' \| 'unfocusedLayer'` · default 'none' Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.
`onFocus`	`(e: React.FocusEvent) => void` Fires when focus enters the search input.
`onBlur`	`(e: React.FocusEvent) => void` Fires when focus leaves the search input.
`xstyle`	`StyleXStyles` StyleX styles for layout customization. Must be a stylex.create() value.

Theming

Targets

astryx-power-search