feat: add Filters component

[ThePrincelle]

🔗 Linked issue

Resolves #5298

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR introduces a complete new Filters component for Nuxt UI, inspired by Linear's filters UI. This component enables developers to create advanced and customizable filtering interfaces for data.

Screenshot_2025-11-10-16.54.54.mp4

What was added:

Main component and sub-components:

• Filters.vue - Main component that manages the display and manipulation of a list of active filters
• FilterItem.vue - Represents an individual active filter with its field, operator, and value selector
• AddFilterPopover.vue - Popover to add new filters with field search
• FilterOperatorDropdown.vue - Dropdown to select a filter operator
• FilterValueSelector.vue - Adaptive value selector based on field type and operator
• FilterContextProvider.vue - Context provider to share configuration between all child components
• SelectOptionsPopover.vue - Popover to select options with search (uses CommandPalette)
• Range value components:
  • FilterDatePicker.vue - Single date selection
  • FilterDateRange.vue - Date range selection
  • FilterTimeRange.vue - Time range selection
  • FilterDateTimeRange.vue - Date/time range selection
  • FilterNumberRange.vue - Number range selection

TypeScript types:

• src/runtime/types/filter.ts - Complete type definitions for the filter system:
  • Supported field types (select, multiselect, date, text, number, boolean, email, url, tel, time, datetime, custom, separator)
  • 30+ available operators (is, is_not, contains, between, greater_than, etc.)
  • Interfaces for field configuration, options, groups, i18n
  • Types for visual variants (solid/outline, sizes, radius)

Utilities:

• src/runtime/utils/operators.ts - Operator management by field type, default i18n configuration
• src/runtime/utils/fields.ts - Utilities to manipulate field configurations (flattening, search, grouping)
• src/runtime/utils/validation.ts - Validation functions for filter values (email, URL, tel, regex, custom)

Composable:

• src/runtime/composables/useFilterContext.ts - Composable to access the shared filter context

Documentation:

• Complete documentation in docs/content/docs/2.components/filters.md with:
  • Usage examples for all field types
  • Advanced configuration (custom operators, validation, nested fields)
  • Complete internationalization guide
  • Full API reference
  • Table of available operators by field type

Playground:

• Demo page in playgrounds/nuxt/app/pages/components/filters.vue

Why this change is required:

This component addresses the need to create complex and flexible filtering interfaces in Nuxt applications. It provides:

• Support for 15+ different field types
• 30+ customizable operators
• Built-in value validation
• Complete internationalization support
• Linear-inspired, modern and intuitive user interface
• Modular and extensible architecture with custom component support
• Hierarchical and grouped field management

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

Known issues :

• In the docs, it seems that the preview of the component is not working completely, maybe an issue with the use of inject Vue method for the context of the filters
• With children elements, I have an issue with the Popover for keyboard navigation. Maybe a refactor of AddFilterPopover.vue is needed for this to be fixed
• All styles are for now hard-coded

PS : I took this component from a project of mine, it does not follow NuxtUI's coding style (yet).

In conclusion, this component is far from perfect at this stage but I think it has the potential to be really useful for the community. We could add an integration with the Table component to make it work with TanStack filtering methods.

Thank you for your consideration ❤️

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@5434

commit: 26136e7

[benjamincanac]

I'd strongly recommend opening up an issue to discuss things first before implementing all of this.

I don't think this belongs into Nuxt UI, the components you made are really specific and not extendable at all with hard-coded logic and styles.

[ThePrincelle]

I'd strongly recommend opening up an issue to discuss things first before implementing all of this.

I don't think this belongs into Nuxt UI, the components you made are really specific and not extendable at all with hard-coded logic and styles.

I understand your concerns, but I'd like to clarify the design approach:

On extensibility:
The component supports 15+ field types natively, plus a custom type for any Vue component. It offers 30+ customizable operators, validation (regex/functions), unlimited hierarchical navigation, and full i18n support. Variants, sizes, and styles are all configurable to a certain level but sadly not yet via the :ui feature.

On logic:
The component contains no filtering logic. It only provides a UI to compose filters and emits a change event with the selected filters. How you filter your data (API, local, etc.) is entirely up to you.

Vision:
I see this similarly to the Table component. It's covering common use cases while remaining flexible. Both could complement each other naturally (filters + data table).

This is my first contribution of this kind. I'm open to feedback and adjustments to align with Nuxt UI's standards. If it doesn't get merged, no worries—it's been a great learning experience contributing to a project with such clean processes and structure. Either way, I hope it can inspire others or contribute to future discussions.

PS : Not to worry, this component was made for a project of mine, I didn't take a lot of time porting this here. Because I wanted to see if it was useful first, I've added the component to the playground with some fake data and filtering logic if someone want's to play with it.