ui/docs/content/1.getting-started/1.index.md

navigation.title, title, description

navigation.title	title	description
Introduction	Nuxt UI v3	A comprehensive, Nuxt-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications.

We're thrilled to introduce this major update to our UI library, bringing significant improvements and powerful new features. Nuxt UI v3 represents a leap forward in creating robust, accessible, and highly customizable user interfaces for Nuxt applications.

What's New in v3?

Radix Vue

We've transitioned from Headless UI to Radix Vue as our core component foundation. This shift brings several key advantages:

• Extensive Component Library: With 55+ primitives, Radix Vue significantly expands our component offerings.
• Active Development: Radix Vue's growing popularity ensures ongoing improvements and updates.
• Enhanced Accessibility: Built-in accessibility features align with our commitment to inclusive design.
• Vue 3 Optimization: Seamless integration with Vue 3 and the Composition API.

This transition empowers Nuxt UI to become a more comprehensive and flexible UI library, offering developers greater power and customization options.

Tailwind CSS v4

Nuxt UI v3 integrates the latest Tailwind CSS v4 alpha (announced March 6, 2024), bringing significant improvements:

• Faster Builds: Up to 10x faster, especially for larger projects.
• Unified Toolchain: Built-in features like vendor prefixing, nesting support, and modern CSS transforms.
• CSS-First Configuration: New @theme directive for easy customization without JavaScript.
• Optimized Performance: Smaller engine footprint and more efficient processing.

::note For a comprehensive overview of Tailwind CSS v4 alpha features, visit the official announcement. ::

Tailwind Variants

We've adopted Tailwind Variants to manage our design system, offering:

• Dynamic Styling: Flexible component variants with a powerful API
• Type Safety: Full TypeScript support with auto-completion
• Conflict Resolution: Efficient merging of conflicting styles

This integration unifies the styling of components, ensuring consistency and code maintainability.

TypeScript Integration

Nuxt UI v3 offers significantly improved TypeScript integration, providing a superior developer experience:

• Enhanced Auto-completion:

  • Full auto-completion for component props based on your theme
  • Intelligent suggestions for app.config.ts theme configuration

• Generic-based Components:

  • Built using Vue 3 Generics
  • Improved type inference for slots and events

• Type-safe Theming:

  • Leveraging Tailwind Variants for type-safe styling options
  • Customizable types for extended theme configurations

::note{to="/components/accordion#with-custom-slot"} Check out an example of the Accordion component with auto-completion for props and slots. ::

Migration

We want to be transparent: migrating from Nuxt UI v2 to v3 will require significant effort. While we've maintained core concepts and components, Nuxt UI v3 has been rebuilt from the ground up, resulting in a new library with enhanced capabilities.

Key points to consider:

• A comprehensive migration guide will be available in the coming weeks.
• Review the new documentation and components carefully before attempting to upgrade.
• If you encounter any issues, please report them on our GitHub repository.

FAQ

::accordion ::accordion-item{label="What are the main considerations when upgrading to Nuxt UI v3?"} The transition to v3 involves significant changes, including new component structures, updated theming approaches, and revised TypeScript definitions. We recommend a careful, incremental upgrade process, starting with thorough testing in a development environment. ::

::accordion-item{label="Will Nuxt UI v3 work with other CSS frameworks like UnoCSS?"} Nuxt UI v3 is currently designed to work exclusively with Tailwind CSS. While there's interest in UnoCSS support, implementing it would require significant changes to the theme structure due to differences in class naming conventions. As a result, we don't have plans to add UnoCSS support in v3. ::

::accordion-item{label="Is Nuxt UI v3 compatible with standalone Vue projects?"} We're planning to add Vue support in the near future. For now, Nuxt UI v3 is only available for Nuxt. Track progress on Vue compatibility in this issue. ::

::accordion-item{label="How does Nuxt UI v3 handle accessibility?"} Nuxt UI v3 enhances accessibility through Radix Vue integration. This provides automatic ARIA attributes, keyboard navigation support, intelligent focus management, and screen reader announcements. While offering a strong foundation, proper implementation and testing in your specific use case remains crucial for full accessibility compliance. For more detailed information, refer to Radix Vue's accessibility documentation. ::

::accordion-item{label="What is the testing approach for Nuxt UI v3?"} Nuxt UI v3 ensures reliability with 800+ Vitest tests, covering core functionality and accessibility. This robust testing suite supports the library's stability and serves as a reference for developers. ::

::accordion-item{label="Is this version stable and suitable for production use?"} As Nuxt UI v3 is currently in alpha, we recommend thorough testing before using it in production environments. We're actively working on stabilization and welcome feedback from early adopters to improve the library. Feel free to report any issues you encounter on our GitHub repository. :: ::

:hr

We're excited about the possibilities Nuxt UI v3 brings to your projects. Explore our documentation to learn more about new features, components, and best practices for building powerful, accessible user interfaces with Nuxt UI v3.