Query

A single-line filter field for a list. Free text and key:value qualifiers mix in one query: is:shared -staging api. The field colors each token in place. A suggestion popover completes keys and values while the caret stays in the field.

A grammar from @ngrok/mantle/query-filter sets the vocabulary. The same grammar filters your items with filterItemsByQuery, so the field and the list always agree.

Type is: to see the values and their live match counts.

Project	Description	Visibility
billing-api	Invoices and payments	Shared
marketing-site	Public website	Shared
design-tokens	Old color scales	Shared
staging-api	Staging API	Private
webhook-tests	Local webhook tests	Private

1import { Button } from "@ngrok/mantle/button";2import { DataTable, createColumnHelper, tableFeatures, useTable } from "@ngrok/mantle/data-table";3import { Empty } from "@ngrok/mantle/empty";4import { type FilterGrammar, filterItemsByQuery } from "@ngrok/mantle/query-filter";5import { Query } from "@ngrok/mantle/query";6import { MagnifyingGlassIcon } from "@phosphor-icons/react/MagnifyingGlass";7import { useDeferredValue, useState } from "react";8 9type Project = {⋯10	id: string;11	name: string;12	description: string;13	shared: boolean;14	archived: boolean;15};16 17const projects: Project[] = [⋯18	{⋯19		id: "p_1",20		name: "billing-api",21		description: "Invoices and payments",22		shared: true,23		archived: false,24	},25	{⋯26		id: "p_2",27		name: "marketing-site",28		description: "Public website",29		shared: true,30		archived: false,31	},32	{⋯33		id: "p_3",34		name: "design-tokens",35		description: "Old color scales",36		shared: true,37		archived: true,38	},39	{⋯40		id: "p_4",41		name: "staging-api",42		description: "Staging API",43		shared: false,44		archived: false,45	},46	{⋯47		id: "p_5",48		name: "webhook-tests",49		description: "Local webhook tests",50		shared: false,51		archived: false,52	},53];54 55const projectFilterGrammar: FilterGrammar<Project> = {⋯56	keys: [⋯57		{⋯58			key: "name",59			aliases: ["title"],60			description: "Text in the project name",61			matches: (project, value) => project.name.toLowerCase().includes(value.toLowerCase()),62		},63		{⋯64			key: "description",65			aliases: ["desc"],66			description: "Text in the description",67			prose: true,68			matches: (project, value) => project.description.toLowerCase().includes(value.toLowerCase()),69		},70		{⋯71			key: "is",72			description: "The project state",73			values: [⋯74				{ value: "shared", description: "Your team can see it" },75				{ value: "private", description: "Only you can see it", aliases: ["personal"] },76				{ value: "archived", description: "Kept for reference" },77			],78			matches: (project, value) => {⋯79				switch (value) {⋯80					case "shared":81						return project.shared;82					case "private":83						return !project.shared;84					case "archived":85						return project.archived;86					default:87						return false;88				}89			},90		},91	],92	getSearchText: (project) => [project.name, project.description, project.id].join("\n"),93};94 95const features = tableFeatures({});96const columnHelper = createColumnHelper<typeof features, Project>();97const columns = columnHelper.columns([⋯98	columnHelper.accessor("name", {⋯99		id: "name",100		header: () => <DataTable.Header>Project</DataTable.Header>,101		cell: (props) => (102			<DataTable.Cell className="text-strong" translate="no">⋯103				{props.getValue()}104			</DataTable.Cell>105		),106	}),107	columnHelper.accessor("description", {⋯108		id: "description",109		header: () => <DataTable.Header>Description</DataTable.Header>,110		cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,111	}),112	columnHelper.accessor((project) => (project.shared ? "Shared" : "Private"), {⋯113		id: "visibility",114		header: () => <DataTable.Header>Visibility</DataTable.Header>,115		cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,116	}),117]);118 119export function QueryExample() {⋯120	const [query, setQuery] = useState("");121	const deferredQuery = useDeferredValue(query);122	const visibleProjects = filterItemsByQuery({⋯123		grammar: projectFilterGrammar,124		items: projects,125		query: deferredQuery,126	});127	const table = useTable({ features, data: visibleProjects, columns });128	const rows = table.getRowModel().rows;129 130	return (131		<div className="w-full space-y-3">⋯132			<Query.Root⋯133				grammar={projectFilterGrammar}134				items={projects}135				value={query}136				onValueChange={setQuery}137			>138				<Query.Input⋯139					aria-label="Filter projects"140					placeholder="Filter projects, or type a filter like is:shared"141				/>142				<Query.Content>⋯143					<Query.List>{(suggestion) => <Query.Item suggestion={suggestion} />}</Query.List>144					<Query.Empty />145					<Query.Footer>⋯146						<Query.Legend />147						<Query.KeyboardHints />148					</Query.Footer>149				</Query.Content>150			</Query.Root>151			<DataTable.Root table={table}>⋯152				<DataTable.Head />153				<DataTable.Body>⋯154					{rows.length > 0 ? (155						rows.map((row) => <DataTable.Row key={row.id} row={row} />)156					) : (157						<DataTable.EmptyRow>⋯158							<Empty.Root>⋯159								<Empty.Icon svg={<MagnifyingGlassIcon />} />160								<Empty.Title>No projects match this filter</Empty.Title>161								<Empty.Actions>⋯162									<Button⋯163										type="button"164										appearance="outlined"165										intent="neutral"166										onClick={() => setQuery("")}167									>168										Clear filter169									</Button>170								</Empty.Actions>171							</Empty.Root>172						</DataTable.EmptyRow>173					)}174				</DataTable.Body>175			</DataTable.Root>176		</div>177	);178}

The query is the only state, and you own it through value and onValueChange. There's no uncontrolled form, because every list that hosts this field already keeps the query somewhere: in component state, in form state, or in the URL. To keep it in ?q=, follow the Query from the URL recipe.

Composition

Query.Root├── Query.Input└── Query.Content    ├── Query.List    │   └── Query.Item    ├── Query.Empty    └── Query.Footer        ├── Query.Legend        └── Query.KeyboardHints

Root lays out its children in one row, so put your own buttons beside the field there. Input is the field. Content is the suggestion popover; without it, the field is a highlighted input with no suggestions.

You compose the popover from its parts:

List is the listbox. Its child is a function that gets each suggestion and returns a Query.Item for it. Pass children to Item to show your own row content.
Empty shows when no suggestion matches. By default, it says what the field accepts at the caret. Pass children to show your own message.
Footer stays under the rows while they scroll. Put Legend, KeyboardHints, and your own content, such as a link to your filter docs, in it.

Leave out a part to remove it. Wrap your own text in Footer in an element, such as a <p>, so it is not bare text beside the legend.

Polymorphism

Query.Root takes asChild. Use it to render the row as your own element, such as a <section> with its own label, while Root keeps the state and the layout classes.

Query.Footer takes asChild. Use it to render the footer as your own element, while the footer keeps its id and the input keeps it as its description.

The other parts don't take asChild:

Input renders the field's shell, its painted copy, and the <input> together.
Content wraps Popover.Content, whose element Radix positions.
List renders the section groups and their headings.
Item must stay the role="option" element that the input names through aria-activedescendant.
Empty, Legend, and KeyboardHints render their own content.

Inline actions and a footer

While the query has text, Query.Input shows a clear button at its right edge. The button empties the query and moves focus back to the field. Set clearLabel to rename it. Set onClear for work that only a clear does, such as applying the empty query at once. Other children of Query.Input render before the clear button. Pass ghost xs icon buttons.

Query.KeyboardHints shows the keys the field answers to. When Enter submits a form, set enterHint to name that action, such as "select, or search". Put your own footer content in Query.Footer, after the hints.

1import { IconButton } from "@ngrok/mantle/button";2import { Query } from "@ngrok/mantle/query";3import { CopyIcon } from "@phosphor-icons/react/Copy";4import { useState } from "react";5 6export function InlineActionsQueryExample() {⋯7	const [query, setQuery] = useState("is:shared ");8 9	return (10		<Query.Root⋯11			className="max-w-xl"12			grammar={projectFilterGrammar}13			items={projects}14			value={query}15			onValueChange={setQuery}16		>17			<Query.Input⋯18				aria-label="Filter projects"19				placeholder="Filter projects, or type a filter like is:shared"20			>21				<IconButton⋯22					type="button"23					appearance="ghost"24					intent="neutral"25					size="xs"26					label="Copy filter"27					icon={<CopyIcon />}28					onClick={() => void navigator.clipboard.writeText(query)}29				/>30			</Query.Input>31			<Query.Content>⋯32				<Query.List>{(suggestion) => <Query.Item suggestion={suggestion} />}</Query.List>33				<Query.Empty />34				<Query.Footer>⋯35					<Query.Legend />36					<Query.KeyboardHints />37					<p>Filters apply as you type.</p>38				</Query.Footer>39			</Query.Content>40		</Query.Root>41	);42}

projectFilterGrammar and projects are the ones from the first example.

Search on the server

When a server runs the query, declare its vocabulary with defineRemoteFilterGrammar and leave out items. The suggestions then carry no counts. The grammar's syntax keeps the highlighting to what the server reads: "qualifiers" (the default) treats only bare key:value tokens as structure, and "conjunction" reads one AND group of exclusions, comma lists, and quotes.

Inside a <form>, Enter submits the form, unless the keyboard made a suggestion active. Then Enter accepts that suggestion.

1import { Button } from "@ngrok/mantle/button";2import { defineRemoteFilterGrammar } from "@ngrok/mantle/query-filter";3import { Query } from "@ngrok/mantle/query";4import { useState } from "react";5 6const accountSearchGrammar = defineRemoteFilterGrammar({⋯7	keys: [⋯8		{⋯9			key: "is",10			description: "The account state",11			values: [{ value: "active" }, { value: "suspended" }, { value: "past_due" }],12		},13		{ key: "email", description: "The account email" },14	],15});16 17export function RemoteQueryExample() {⋯18	const [query, setQuery] = useState("");19	const [submittedQuery, setSubmittedQuery] = useState<string | null>(null);20 21	return (22		<form⋯23			className="w-full max-w-xl space-y-3"24			onSubmit={(event) => {⋯25				event.preventDefault();26				setSubmittedQuery(query);27			}}28		>29			<Query.Root grammar={accountSearchGrammar} value={query} onValueChange={setQuery}>⋯30				<Query.Input⋯31					aria-label="Search accounts"32					placeholder="Search accounts, or type a filter like is:suspended"33				/>34				<Button type="submit" appearance="outlined" intent="neutral">⋯35					Search36				</Button>37				<Query.Content>⋯38					<Query.List>{(suggestion) => <Query.Item suggestion={suggestion} />}</Query.List>39					<Query.Empty />40					<Query.Footer>⋯41						<Query.Legend />42						<Query.KeyboardHints />43					</Query.Footer>44				</Query.Content>45			</Query.Root>46			<p className="text-muted text-sm">⋯47				{submittedQuery == null ? "Press Enter to search." : `The server runs: ${submittedQuery}`}48			</p>49		</form>50	);51}

Large lists

The match counts and the live filter each run one pass over items per keystroke. For thousands of rows, or a list that streams in, apply the query on Enter: wrap the field in a <form>, leave out items, and set enterHint on Query.KeyboardHints. Enter with no active suggestion submits the form. The Query from the URL recipe has the hook and a demo.

Filter from a value

To let a person select a value in a table row and get its filter, call toggleFacet in the click handler. The Filter from a value recipe has the demo.

Token colors

Keys, values, and OR take the colors that Code Block gives attributes, strings, and operators, so a query reads like the code on the same page. Set the three CSS variables on the field or any ancestor to change them. This calmer set colors only the keys:

1import { Query } from "@ngrok/mantle/query";2import { useState } from "react";3 4export function TokenColorsQueryExample() {⋯5	const [query, setQuery] = useState("is:shared OR name:api");6 7	return (8		<Query.Root⋯9			grammar={projectFilterGrammar}10			items={projects}11			value={query}12			onValueChange={setQuery}13			className="max-w-xl [--query-operator-color:var(--shiki-token-keyword)] [--query-value-color:var(--text-color-strong)]"14		>15			<Query.Input⋯16				aria-label="Filter projects"17				placeholder="Filter projects, or type a filter like is:shared"18			/>19			<Query.Content>⋯20				<Query.List>{(suggestion) => <Query.Item suggestion={suggestion} />}</Query.List>21				<Query.Empty />22				<Query.Footer>⋯23					<Query.Legend />24					<Query.KeyboardHints />25				</Query.Footer>26			</Query.Content>27		</Query.Root>28	);29}

Accessibility

The field is a real <input role="combobox"> with aria-autocomplete="list". The text you edit is the input's own value, so the caret, selection, IME composition, paste, and undo all stay native. A painted copy of the text sits over the input and is hidden from assistive tech.

Focus never leaves the input. The active suggestion is announced through aria-activedescendant.
No suggestion is active until an arrow key moves. Up and Down wrap around the list. A pointer over a row highlights it but doesn't arm Enter.
Enter accepts the active suggestion. With no active suggestion, Enter closes the list and lets the event reach your form. Escape closes the list.
A caret move retires the active suggestion, so Enter can't accept a row from a list you didn't see.
While an IME composes, every key goes to the IME.
While the popover is open, Query.Footer joins the input's accessible description, after any description you set. While no suggestion matches, Query.Empty joins it too.

Name the field with aria-label, or put it in a Field and label it with Field.Label. Inside Field.Control, the field takes its id, name, aria-describedby, aria-errormessage, and aria-invalid from the Field.Item.

The section headings ("Filter by", "Exclude", "Values"), the legend, the keyboard hints, and the default empty message are English copy that mantle sets. The listbox name defaults to "Filter suggestions"; set aria-label on Query.List to change it.

API Reference

Query.Root

The row and the state owner. It renders a div that lays out its children in a row, and accepts every div prop.

Prop	Type	Default	Description
`grammar`	`FilterGrammar<Item>`	none	The grammar of this list's filter language. Declare it as a module constant: the engine caches its tables per object.
`items`	`Item[]`	none	The unfiltered items, for the live match counts. Leave it out when a server runs the query; the suggestions show no counts.
`value`	`string`	none	The query, exactly as typed. Required.
`onValueChange`	`(value: string) => void`	none	Called with the whole query on every edit, typed or inserted. Required.
`asChild`	`boolean`	`false`	Render the row as the child element and merge the props onto it.

Data Attribute	Value	Description
`data-slot`	`"query"`	On the row element.

Query.Input

The query field. className and style go to the field's outer element, as on Input. All other props go to the <input>, such as ref, id, name, disabled, required, readOnly, validation, the aria-* props, and the event handlers. A disabled or read-only field shows no suggestions and no clear button.

Prop	Type	Default	Description
`placeholder`	`string`	none	Placeholder copy. Name one example filter the grammar accepts. Required.
`aria-label`	`string`	none	The accessible name. Leave it out when `Field.Label` names the field.
`suggestOnFocus`	`boolean`	`true`	Whether focus alone opens the suggestions. Set `false` when you move focus into the field for the user, as on a dialog open.
`children`	`ReactNode`	none	Inline actions inside the field at its right edge, before the clear button.
`clearLabel`	`string`	`"Clear filter"`	The accessible name and tooltip of the clear button.
`onClear`	`() => void`	none	Called after the clear button empties the query.
`ref`	`Ref<HTMLInputElement>`	none	The `<input>` element.
`validation`	`"error"` \| `"success"` \| `"warning"` \| `false` \| `() => "error" \| "success" \| "warning" \| false`	none	The validation state. It sets the border, and `"error"` also sets `aria-invalid`. Inside `Field.Control`, the `Field.Item` sets it.
`aria-describedby`	`string`	none	The field's own description. `Query.Footer` joins it while the popover is open.

CSS Variable	Default	Description
`--query-key-color`	`var(--shiki-token-attribute)`	The color of a qualifier key.
`--query-value-color`	`var(--shiki-token-string)`	The color of a qualifier value.
`--query-operator-color`	`var(--shiki-token-operator)`	The color of `OR` and `AND`.

Data Attribute	Value	Description
`data-slot`	`"query-input"`	On the field's outer element.
`data-slot`	`"query-input-actions"`	On the `span` that wraps the children. The clear button follows it. It has `display: contents`, so each child lays out in the row.
`data-slot`	`"input"`	On the field's chrome, inside `"query-input"`, as on `Input`.
`data-disabled`	present	On the `"input"` chrome while the field is disabled.
`data-validation`	`"error"` \| `"success"` \| `"warning"`	On the `"input"` chrome. Omitted when unset.

Query.Content

The suggestion popover. It holds the parts you compose into it and keeps focus in the field. It accepts the Popover.Content props except the ones it owns: align, role, preferredWidth, the auto-focus handlers, and onInteractOutside.

Prop	Type	Default	Description
`children`	`ReactNode`	none	The parts: `Query.List`, `Query.Empty`, and `Query.Footer`. Required.
`className`	`string`	none	Classes for the popover.
`ref`	`Ref<HTMLDivElement>`	none	The popover element.
`side`, `sideOffset`, `id`, `style`, `aria-`, `data-`		none	Go to the popover, as on `Popover.Content`.

Data Attribute	Value	Description
`data-slot`	`"query-content"`	On the popover, beside `"popover-content"`.
`data-state`	`"open"` \| `"closed"`	On the popover, from Radix.
`data-side`	`"top"` \| `"bottom"`	On the popover: the side it opened on.
`data-align`	`"start"`	On the popover.

Query.List

The suggestion listbox for the token under the caret. It groups the rows under "Filter by", "Exclude", and "Values", and it scrolls when the rows don't fit. It accepts every div prop except id and role.

Prop	Type	Default	Description
`children`	`(suggestion: FilterSuggestion) => ReactNode`	none	Renders one suggestion. Return a `Query.Item` for every suggestion, because the arrow keys move through every one. Required.
`aria-label`	`string`	`"Filter suggestions"`	The accessible name of the listbox.

Data Attribute	Value	Description
`data-slot`	`"query-list"`	On the listbox.

Query.Item

One suggestion row: a role="option" that inserts its suggestion on a click. The arrow keys in the field make a row active, and Enter inserts it. It accepts every div prop except id, role, tabIndex, and aria-selected. Your event handlers run first; call preventDefault() in onClick to skip the insert.

Prop	Type	Default	Description
`suggestion`	`FilterSuggestion`	none	The suggestion this row inserts. Pass the one `Query.List` hands its function. Required.
`children`	`ReactNode`	none	The row's content. When omitted, the row shows the label, the description, and the match count.

Data Attribute	Value	Description
`data-slot`	`"query-item"`	On the option.
`data-highlighted`	present	While the row is active, or under the pointer with no active row.

Query.Empty

The message that shows in place of the rows when no suggestion matches. It accepts every div prop except id.

Prop	Type	Default	Description
`children`	`ReactNode`	none	The message. When omitted, it says what the field accepts at the caret.

Data Attribute	Value	Description
`data-slot`	`"query-empty"`	On the message.

Query.Footer

The area under the rows, pinned while the rows scroll. It accepts every div prop except id. The footer sets its own id, so the field can name it as its description. With asChild, that id replaces the id of the child.

Prop	Type	Default	Description
`children`	`ReactNode`	none	`Query.Legend`, `Query.KeyboardHints`, and your own content.
`asChild`	`boolean`	`false`	Render the footer as the child element and merge the props onto it.

Data Attribute	Value	Description
`data-slot`	`"query-footer"`	On the footer.

Query.Legend

The syntax reminder. It shows only the syntax the grammar honors. It accepts every p prop except children.

Data Attribute	Value	Description
`data-slot`	`"query-legend"`	On the legend.

Query.KeyboardHints

The keys the field answers to: the arrows, Enter, and Escape. It accepts every p prop except children.

Prop	Type	Default	Description
`enterHint`	`string`	`"select"`	What Enter does. Name your action when Enter submits a form.

Data Attribute	Value	Description
`data-slot`	`"query-keyboard-hints"`	On the hints.