v3

[benjamincanac]

The development is ongoing on the v3 branch of this repository: https://github.com/nuxt/ui/tree/v3.

---

A lot has changed since @nuxt/ui was made open-source (May 2023), so the plan here is to rewrite every component from scratch alongside their config.

I'll post regular updates on this issue and on https://twitter.com/benjamincanac.

Overview

• [x] Tailwind v4 https://tailwindcss.com/blog/tailwindcss-v4-alpha
• [x] #409 which should solve all v3.0 issues
• [x] Switch our internal useUI for https://www.tailwind-variants.org/
• [x] Generic components
• [x] Remove safelists by compiling the theme on build based on pre-defined colors
• [x] Tests
• [ ] #2129

Documentation

https://ui3.nuxt.dev

Breaking Changes

The biggest change is the switch to tailwind-variants, this will cause lots of breaking changes if you've used the ui prop or app.config.ts to override the config. I apologize in advance for this but I strongly believe this will be beneficial and will bring consistency across all components.

At the beginning the config was split in many keys for the same div to give more flexibility, but since then we introduced tailwind-merge which now allows us to group those keys together, this is a good opportunity to clean the whole thing.

The config will now have a slots amongst other keys that will specifically target dom nodes. The ui prop will only allow you to target those slots.

These changes alongside the refactor of all components will also improve the types, the app.config.ts and ui props are now perfectly typed, as well as all components props, slots, emits and expose.

Feel free to comment on this if you have any ideas for the next major.

### Components
- [x] Accordion
- [x] Alert
- [x] Avatar
- [x] AvatarGroup
- [x] Badge
- [x] Breadcrumb
- [x] Button
- [x] ButtonGroup
- [x] Card
- [ ] Carousel
- [x] Checkbox
- [x] Chip
- [x] Collapsible
- [x] CommandPalette
- [x] Container
- [x] ContextMenu
- [x] Drawer
- [x] DropdownMenu (Dropdown)
- [x] Form
- [x] FormField (FormGroup)
- [x] Icon
- [x] Input
- [x] InputMenu
- [x] Kbd
- [x] Link
- [x] Modal
- [x] NavigationMenu (HorizontalNavigation/VerticalNavigation)
- [x] Pagination
- [x] Popover
- [x] Progress
- [x] Provider
- [x] RadioGroup
- [x] Select
- [x] SelectMenu
- [x] Separator (Divider)
- [x] Skeleton
- [x] Slideover
- [x] Slider (Range)
- [ ] Table
- [x] Tabs
- [x] Textarea
- [x] Toast (Notification)
- [x] Switch (Toggle)
- [x] Tooltip

[sandros94]

I would like to help, if I'm able to. Is there going to be a dedicated branch or will it be done in the dev one?

[benjamincanac]

Once we start this, there will be indeed a new branch with auto-release so we can try it out and especially keep working on the v2 as it might take some time. I'll create new issues once this gets started with the remaining things to do 😊

[jd-solanki]

Hi @benjamincanac

I have few design ideas if you are open to this I would like to share it for the future of Nuxt UI 3. Should we discuss this in this issue or it'll be better to discuss design ideas in seperate discussion thread?

[benjamincanac]

@jd-solanki You can share them here!

[sawa-ko]

Since it is supposed to be a refactoring to all components, could we give the possibility of compatibility with unocss?

[benjamincanac]

@sawa-ko It will be made with Tailwind v4. To what end would you make it compatible with Uno?

[benjamincanac]

I've started working on this in a private repository of mine, I'll open-source it once I'm satisfied with the base so you guys can check it out 😊.

A lot has changed since @nuxt/ui was made open-source (May 2023), so the plan here is to rewrite every component from scratch alongside their config. For example, at the beginning the config was split in many keys for the same div to give more flexibility, but since then we introduced tailwind-merge which now allows us to group those keys together.

I'll post regular updates on this issue.

[ghost]

Please tell me how long it will take for this upgrade to be available. Very much looking forward to this upgrade

[benjamincanac]

I have no idea how long it will take and it's not entirely up to us, I hope to release it at the same time as the official release of Tailwind v4.

[robin-dongbin]

That's awesome. The new version of nuxt-ui uses exactly the tech stack I expected.

I tried to build my own UI library using radix-ui and tailwind-variants, but I immediately found that even with radix-ui, it is not easy to build a full UI library.

But I got an idea with an API that works with any design language. If you are interested, here is my demo repository: https://github.com/vincajs/vinca-ui

[benjamincanac]

@robin-dongbin It's already in the making. There are already 13 components done, 36 more to go 😅

[robin-dongbin]

Since the component library is based on radix-ui without styles, I thought it would be nice to provide an api that is abstracted from various design systems, so you can switch styles from one system to another at any time.

If people want to implement another design system, they can just customize it, share files, or even contribute to a repository.

Taking things a step further, it is possible to switch between different design systems at runtime.

Of course, I'm just offering an idea, and if you think it's too late, that's fine

[benjamincanac]

This is actually already what we're doing with the App Config. You can customize the classes for every part of every component.

[aspitrine]

Thanks for the work! i’m impatient to try this!

Just one question :

The biggest change is the switch to tailwind-variants, this will cause lots of breaking changes if you've used the ui prop or app.config.ts to override the config.

app.config.ts is deprecated and it will not port in v3? Or it’s something else?

[benjamincanac]

No we keep the app.config.ts, what I meant is since we now use tailwind-variants the config itself changes.

For example the Kbd component, its config looked like this:

export default {
  base: 'inline-flex items-center justify-center text-gray-900 dark:text-white',
  padding: 'px-1',
  size: {
    xs: 'h-4 min-w-[16px] text-[10px]',
    sm: 'h-5 min-w-[20px] text-[11px]',
    md: 'h-6 min-w-[24px] text-[12px]'
  },
  rounded: 'rounded',
  font: 'font-medium font-sans',
  background: 'bg-gray-100 dark:bg-gray-800',
  ring: 'ring-1 ring-gray-300 dark:ring-gray-700 ring-inset',
  default: {
    size: 'sm'
  }
}

Here is the new version:

export default {
  base: 'inline-flex items-center justify-center text-gray-900 dark:text-white px-1 rounded font-medium font-sans bg-gray-50 dark:bg-gray-800 ring ring-gray-300 dark:ring-gray-700 ring-inset',
  variants: {
    size: {
      xs: 'h-4 min-w-[16px] text-[10px]',
      sm: 'h-5 min-w-[20px] text-[11px]',
      md: 'h-6 min-w-[24px] text-[12px]'
    }
  },
  defaultVariants: {
    size: 'sm'
  }
}

This is a breaking change if you've overridden its config in your app.config.ts or through the ui prop. I'm thinking of a CLI or something that would help people migrate from v2 to v3 without too much trouble but it might not be easy to achieve. Everything is fully typed so this will give some indications at least.

[aspitrine]

Ok !

Effectively, it's a breaking change but it seam ok for the future to have a better granularity with the variants.

Thanks for the explanation and the example 🙏🏻

[robin-dongbin]

Here are some thoughts on the new version:

1. VerticalNavigation / HorizontalNavigation should be NavigationMenu with an orientation prop
2. Notification should rename to 'Toast', now we have Notification component and 'useToast' function, that is confused. and for new version I hope we support runtime placement.
3. Table should be a simple wrapper of primitive table no more features. (Building a complete data table is very complex)
4. As an alternative provide a DataTable component for more complex usage. Recommended use https://github.com/TanStack/table.
5. InputMenu rename to Autocomplete
6. SelectMenu rename to Combobox. In fact, I recommend the same naming for everything as radix, which makes more sense.

[robin-dongbin]

This is actually already what we're doing with the App Config. You can customize(自定义) the classes for every part of every component.

I think the API I envision is better in this regard. Because you can provide multiple design system presets in the repository for users to choose from, switching styles is easy. For now, of course, you can just provide one preset, nuxt style But it does reserve an easier way to extend it to implement more design systems.like Material Design, Ant Design and so on

[MickL]

I agree with everything @robin-dongbin said, except for the Table I am not sure about this one.

Notification should rename to 'Toast', now we have Notification component and 'useToast' function, that is confused. and for new version I hope we support runtime placement.

Otherwise useToast() could be named useNotification() instead. I mean why is it named toast in the first place? I am not a native english speaker but I couldnt find another translation for toast than the bread (toast is not actual bread but you know what I mean).

[messenjer]

@MickL Toast is widely used in UI/UX for a quick message that shows up and then disappears, just like how toast pops out of a toaster when it's ready.

In Radix the component name is Toast https://www.radix-vue.com/components/toast.html

[divine]

Hello,

I'm really sorry but decision to use radix vue is the worst thing happening to this library. It will be a pain in the future for sure.

I don't like how tailwind team abandoned silently headless-ui but at least it's being supported and proven to work without much issues.

You shouldn't be relaying on the library that has over 33 open issues and the author doesn't even know how to fix some issues.

Just my 2 cents.

[benjamincanac]

@divine I'm sorry but I completely disagree with you, @zernonia has been doing an amazing job on Radix Vue with weekly releases https://github.com/radix-vue/radix-vue/releases, 33 issues is nothing for a UI library.

[benjamincanac]

@robin-dongbin Thanks for the suggestions! Regarding the NavigationMenu component replacing VerticalNavigation and HorizontalNavigation, do you think it should use https://www.radix-vue.com/components/navigation-menu.html underneath?

As for the Table component, as mentioned in https://github.com/nuxt/ui/issues/653 I'll try @tanstack/vue-table.

What is your suggestion for the preset system?

I'm not sure about the InputMenu / SelectMenu rename though as the Combobox is a primitive that will be used in multiple components like CommandPalette much like the Dialog being used in Modal and Slideover.

[Gerbuuun]

@divine I'd argue that Nuxt UI adopting Radix Vue will make Radix Vue even better and in turn Nuxt UI, benefitting both. Also, most issues are feature requests and not bugs (7 out of 33)

[MickL]

@messenjer thanks for clarifying! I would still propose to rename useToast() to useNotification() as it is way more clear than the image of a jumping toast.

P.S. I am very excited for v3 :)

[Gerbuuun]

Also my view on the naming of "notifications". There is also the browser's notification for desktop/mobile notifications. Some could argue that this would be confusing as well. VueUse named it useWebNotification so the imports do not conflict but still...

[benjamincanac]

I think I will rename it to Toast to match Radix Vue component as suggested by @robin-dongbin and keep useToast(). This prevents any breaking change as you don't have to instantiate this component yourself.

[MickL]

Also my view on the naming of "notifications". There is also the browser's notification for desktop/mobile notifications. Some could argue that this would be confusing as well. VueUse named it useWebNotification so the imports do not conflict but still...

It is not named browser toasts tho, as well as notifications on the desktop or smartphone are not named toast. They are all notifications and toast is confusing imo :)

[robin-dongbin]

@benjamincanac Yes, I mean to use https://www.radix-vue.com/components/navigation-menu.html under the hood

In fact, I think if radix provides relevant components, I think we should use the components provided by radix as much as possible to obtain better accessibility and reduce the maintenance burden.

On the basis of ensuring the implementation of all the components provided by radix, we should build some basic components that radix does not provide, such as Button, Input etc., as well as combined components based on the combination of basic components and radix components, such as Drawer

After that, I don't know if radix plans to provide more advanced components. Like Datatable,Uploader, After all, they just provided the Calendar,In my opinion, this is an advanced component. All the advanced components I think mean complexity. It takes a lot of time to build such components. If radix does not plan to provide them, maybe we can choose mature open source third-party headless components. Such as tanstack/vue-table.

About the preset system, That's what I said above. I tried to make a demo myself. https://github.com/vincajs/vinca-ui, just has a few base component, But it can already explain the api to you that I imagined. If you are interested, just take 2 minutes to check the repository.

[jd-solanki]

@jd-solanki You can share them here!

Thanks, I'll write everything I have in mind for Anu v1 and as Nuxt UI 3 is going to use Radix I don't want to write another lib that does the same thing. Below list will also have my own thoughts & opinions so feel free to discuss or skip them.

1. Along with components like Alert that has props like icon, title, description if we provide low level components like AlertTitle, AlertDescription as well that will cover all the cases like we might want alert with some weird or special structure in other parts of site like landing pages. You can even consider collapsible component which can be used in admin side and also completly differently on landing pages for FAQ.
2. Supporting above point, Providing component locally like shadcn will make users of the lib adopt the lib. Here's why: We built admin templates and we're now going for RadixVue but we decided to go fo Shadcn for now instead of nuxt UI because in worst case scenario if the bug or issue come up we can fix that locally and make a new release without relying on third party lib. Another case can be, We may want some change that lib author might not prefer adding to their own lib so in this case having component locally can also benefit both user of the lib and lib author. I strongly support this point and would love to see local components with Nuxt UI 3.
3. Naming & Component API should be carefully picked considering future CSS & HTML updates to avoid introducing breaking changes after v3 release. For example, we're discussing about toast & notification. Another example is chip, If you ask me it's better named as badge instead of chip because chip is generally like this (Chip & badge are two different things and can co-exist).
4. In case of breaking changes we can use soft deprecation to avoid more work for users.

You can also read my thoughts here.

Unfortunately, I don’t have enough time these days to fully contribute to the v3 project. However, if you are willing to provide components locally, I would be more than happy to help in any way I can.

[benjamincanac]

What do you guys think of removing the USelect in favor of USelectMenu (would be renamed to USelect)? Is there some cases where we specifically need native <select>?

[Gerbuuun]

Questions I have on this:

• Is the USelectMenu just as accessible as the native <select>?
• What about mobile? I like to have select menu's native behaviour on mobile if I don't need any styling. Do we lose this?
• Do you think having something like a prop (<USelect native>) would be a good idea? Does it make sense?

Mostly the mobile behaviour is what concerns me a little.

[benjamincanac]

If we use the Select from Radix Vue, it will be accessible yes: https://www.radix-vue.com/components/select. It renders an hidden <select> underneath. You can take a look on mobile how it behaves.

Not sure how we can handle the search with this though.

[MickL]

It would be great if Modal will have some variants like small, medium, large, fullscreen. Currently it is very cumberstone to change the width of it.

[benjamincanac]

@MickL You can actually change the width quite easily by using :ui="{ width: 'sm:max-w-xl' }", in v3 you will even be able to do this directly with class.

[MickL]

I know but it would be nice to have some options like small, medium, large, fullscreen. It is the same as you would say we can change color of a button easily but it is nice to have color and variant props.

[copofe]

wow! vue compatibility, thanks for the work!

[robin-dongbin]

How about rename leading and trailing to prefix and suffix. This is how most UI libraries are named

[sandros94]

Just a small thought: with the radix-vue implementation, is it planned to drop popperjs? This was discussed in #409(comment) but not updated here

[benjamincanac]

It's implicit yes as Radix Vue uses Floating UI underneath (the new version of popper) so we don't have to.

[lyneal]

@sawa-ko It will be made with Tailwind v4. To what end would you make it compatible with Uno?

Because it can be done. Because UNOCSS is better. Because it was created by a member of the nuxt team.

[bbhxwl]

When is the expected release of the new version?

[HigherOrderLogic]

Do you intend to implement virtual scroll for UTable or you gonna leave it to the users to decide how they want to do it?

[MuhammadM1998]

Thanks for the amazing work I was coming here to suggest a better config setup and I found it was already changed to a better one!

I'd like to suggest also integrating tailwindcss-animate plugin.

[benjamincanac]

It would be nice if Tailwind CSS v4 had plugins 😅 We'll have to wait and see how they implement it.

[MuhammadM1998]

Oh you're right forgot about that

[maximepvrt]

What do you guys think of removing the USelect in favor of USelectMenu (would be renamed to USelect)? Is there some cases where we specifically need native <select>?

The new USelect must allow group management (as \<optgroup> native element) ;-) available in https://www.radix-vue.com/components/select

[bbhxwl]

Can ui 2.x.x be upgraded to ui 3.x.x?

[DavidDeSloovere]

Can ui 2.x.x be upgraded to ui 3.x.x?

Yes, but not without some effort from your part. Breaking changes are listed at the initial post.

[Celibioux]

Just a thought ( you could ignore it if it's out of scoop) But it would't be great to have a switch for Styled / Unstyled components as Primevue did ?