Advanced Filter

An advanced filter component with expression input and visual builder.

vu-advanced-filter · @velkin/react-pro/advanced-filter

Copy page

Import

React

npm i @velkin/react-pro

import { LicenseInfo } from "@velkin/license";
// Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY
// Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY
LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? "");

// @velkin-pro
import { VuAdvancedFilter } from "@velkin/react-pro/advanced-filter";

Examples

API

Props

Prop	Type	Default	Description
columns	VuAdvancedFilterColumn[]	[]	Columns referenceable in expressions. Default: `[]`.
query	`string`	""	Controlled expression text. Default: `""`.
label	`string`	""	Accessible name override for the expression input. Default: `""`.
placeholder	`string`	""	Placeholder override for the expression input. Default: `""`.
valueProvider	`null \| (field: string) => string[]`	null	Supplies value suggestions per column key. Default: `null`.
open	`boolean`	false	Whether the visual builder popover is open. Default: `false`.
disabled	`boolean`	false	Disables the field, suggestions, and builder. Default: `false`.
size	VuAdvancedFilterSize	"md"	Density scale for overlays and inner controls. Default: `"md"`.
tone	VuAdvancedFilterTone	"normal"	Neutral surface weight for the field and overlays. Default: `"normal"`.
placement	VuAdvancedFilterPlacement	"bottom"	Preferred builder placement before flip. Default: `"bottom"`.
align	VuAdvancedFilterAlign	"end"	Builder alignment along the field edge. Default: `"end"`.
offset	`number`	6	Gap in px between the field and the builder popover. Default: `6`.
width	`string`	""	Builder panel inline size; empty uses stylesheet default. Default: `""`.
maxHeight	`string`	""	Max block size of the suggestions list; empty uses default. Default: `""`.
radius	`string`	""	Corner radius for the field, suggestions, and builder; empty uses token defaults. Default: `""`.

Events

Event	Detail	Description
vu-change	VuAdvancedFilterChangeDetail	When the expression text changes.
—	`—`	{CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (v-model).
vu-open	`CustomEvent<void>`	When the builder begins opening.
vu-close	`CustomEvent<void>`	When the builder begins closing.

CSS parts

Part	Description
field	Input field wrapper.
input	Native expression input.
clear	Clear-expression button.
builder-trigger	Visual builder toggle button.
suggestions	Type-ahead suggestions list.
builder	Visual builder popover surface.
builder-dialog	Expanded builder dialog surface.

Methods

Method	Description
show	- Opens the visual builder popover.
hide	- Closes the visual builder popover.
toggle	- Toggles the visual builder popover.
focus	- Focuses the expression input.

Types

Name	Definition
VuAdvancedFilterAlign	`"start" \| "center" \| "end"`
VuAdvancedFilterChangeDetail	`{ query: string; }`
VuAdvancedFilterPlacement	`"top" \| "bottom" \| "left" \| "right" \| "auto"`
VuAdvancedFilterSize	`"sm" \| "md" \| "lg"`
VuAdvancedFilterTone	`"subtle" \| "normal" \| "strong"`
VuAdvancedFilterValueProvider \| null	`null \| (field: string) => string[]`

Import

React

npm i @velkin/react-pro import { LicenseInfo } from "@velkin/license"; // Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY // Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? ""); // @velkin-pro import { VuAdvancedFilter } from "@velkin/react-pro/advanced-filter";

API

Props

Prop	Type	Default	Description
columns	VuAdvancedFilterColumn[]	[]	Columns referenceable in expressions. Default: `[]`.
query	`string`	""	Controlled expression text. Default: `""`.
label	`string`	""	Accessible name override for the expression input. Default: `""`.
placeholder	`string`	""	Placeholder override for the expression input. Default: `""`.
valueProvider	`null \| (field: string) => string[]`	null	Supplies value suggestions per column key. Default: `null`.
open	`boolean`	false	Whether the visual builder popover is open. Default: `false`.
disabled	`boolean`	false	Disables the field, suggestions, and builder. Default: `false`.
size	VuAdvancedFilterSize	"md"	Density scale for overlays and inner controls. Default: `"md"`.
tone	VuAdvancedFilterTone	"normal"	Neutral surface weight for the field and overlays. Default: `"normal"`.
placement	VuAdvancedFilterPlacement	"bottom"	Preferred builder placement before flip. Default: `"bottom"`.
align	VuAdvancedFilterAlign	"end"	Builder alignment along the field edge. Default: `"end"`.
offset	`number`	6	Gap in px between the field and the builder popover. Default: `6`.
width	`string`	""	Builder panel inline size; empty uses stylesheet default. Default: `""`.
maxHeight	`string`	""	Max block size of the suggestions list; empty uses default. Default: `""`.
radius	`string`	""	Corner radius for the field, suggestions, and builder; empty uses token defaults. Default: `""`.

Events

Event	Detail	Description
vu-change	VuAdvancedFilterChangeDetail	When the expression text changes.
—	`—`	{CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (v-model).
vu-open	`CustomEvent<void>`	When the builder begins opening.
vu-close	`CustomEvent<void>`	When the builder begins closing.

CSS parts

Part	Description
field	Input field wrapper.
input	Native expression input.
clear	Clear-expression button.
builder-trigger	Visual builder toggle button.
suggestions	Type-ahead suggestions list.
builder	Visual builder popover surface.
builder-dialog	Expanded builder dialog surface.

Methods

Method	Description
show	- Opens the visual builder popover.
hide	- Closes the visual builder popover.
toggle	- Toggles the visual builder popover.
focus	- Focuses the expression input.

Types

Name	Definition
VuAdvancedFilterAlign	`"start" \| "center" \| "end"`
VuAdvancedFilterChangeDetail	`{ query: string; }`
VuAdvancedFilterPlacement	`"top" \| "bottom" \| "left" \| "right" \| "auto"`
VuAdvancedFilterSize	`"sm" \| "md" \| "lg"`
VuAdvancedFilterTone	`"subtle" \| "normal" \| "strong"`
VuAdvancedFilterValueProvider \| null	`null \| (field: string) => string[]`

Import

Examples

API

Props

Events

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

CSS parts

Methods

Types

Related

Inputs

Guides

Browse