feat: add Filters component

[ThePrincelle]

🔗 Linked issue

Resolves #5298

❓ Type of change

• [x] 📖 Documentation (updates to the documentation or readme)
• [ ] 🐞 Bug fix (a non-breaking change that fixes an issue)
• [ ] 👌 Enhancement (improving an existing functionality)
• [x] ✨ 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.

https://github.com/user-attachments/assets/9c6bd347-cdbe-43bf-94d2-f59b3aa0d93d

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.
• [x] 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[bot]]

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

commit: 26136e7

[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.

[septatrix]

I think if this also supported AND/OR conjuctions (and thus nesting with parenthesis) it would be perfect and I already have several areas in mind where I could replace homegrown solutions. It seems great from a first look (the video and the description, have not checked it out locally).

Unlike benjamin I do not think this is too specific (expendability using slots etc I have not yet checked). There is generally a limited set of types with their respective operations/filters¹. If those are covered this is good for 95% which seems on par with the table, form etc components.

¹ What I can currently think of:

• Number -> less than, greater than, (not) equal, ...
• Date -> (same as above), plus weekday
• String - > length, substring, starts with/ends with, regex
• Sets -> must be one of, must be all of