# PowerSearch

- Page: https://jiguang132.com/resources/astryx/docs/power-search
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt