PowerSearch
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.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| config * | PowerSearchConfig | Configuration defining available fields, operators, and their value types. | |
| filters * | ReadonlyArray<PowerSearchFilter> | Currently active filters. | |
| onChange * | (filters: ReadonlyArray<PowerSearchFilter>, changeType: 'add' | 'edit' | 'remove', index: number) => void | Called when filters change. changeType is 'add', 'edit', or 'remove'. index is the affected filter's position. | |
| label | string | 'Search' | Accessible label for the search input. |
| isLabelHidden | boolean | true | Visually hides the label while keeping it accessible. |
| placeholder | string | 'Search...' | Placeholder text shown when no filters are selected. |
| hasAutoFocus | boolean | false | Auto-focus the input on mount. |
| hasClear | boolean | true | Show a clear-all button for removing all filters. |
| isReadOnly | boolean | false | Prevent adding, editing, or removing filters. |
| isDisabled | boolean | 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. | |
| statusVariant | 'attached' | 'detached' | '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 | 40 | Max character length for filter value display in tokens. |
| maxOperatorMenuItems | number | 10 | Maximum suggestions shown in string and entity value typeaheads. Does not affect the main field search menu or enum value menus. |
| maxSearchResults | number | 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 | '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. | |
| 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' | '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' | '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. |
Usage guidance
- 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.
- Avoid: Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.
- Avoid: 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.
Theming API
{
"targets": [
{
"className": "astryx-power-search"
}
]
}
Examples
- Power Search: Token-based filter bar with enum and text fields, pre-populated with sample filters.
- PowerSearch — Content Search: Power search with contentSearchFieldKey so free-text input maps to a title field automatically.
- PowerSearch — Full Featured: Power search with multiple field types: enum, multi-select, entity, and text filters.
- PowerSearch — Preset Filters: Power search initialized with pre-set filter tokens for status and priority.
- PowerSearch — Search with Table: Composition of PowerSearch with Table using usePowerSearchConfig to auto-generate config and filter data.