Migration guide to PrimeVue v4.

At PrimeTek, we have been developing UI component libraries since 2008. The web continues to undergo technological advancements, and as a result, we have to modernize and update our libraries to stay relevant. PrimeVue v4 is the next-generation version that fully embraces modern Web APIs and removes technical debt like the legacy-styled mode. As part of our commitment to our products and the community, PrimeVue v3 will continue to be maintained until the end of 2024.

The most notable feature is the new styled mode implementation. Previous iterations use SASS at an external repo called primevue-sass-theme which requires compilation of a theme.css file. This file had to be included in the application and need to be swapped at runtime for basic tasks like dark mode or primary color changes. In v4, styled mode is now part of the core, SASS is not used at all, and a new design token based architecture that fully utilizes CSS variables has been created. The new API is modern and superior to the legacy styled mode.

The styled mode theming has been reimplemented from scratch based on an all-new architecture. There is no theme.css involved, so you need to migrate to the API. Currently, Aura is the only available built-in preset; however, by v4 final, two more presets named Lara and Nora would be included, as well as the Material Design theme. If you had a custom theme for v3, the theme needs to be recreated using the new APIs. See the customization section at styled mode for details.

  • Files under primevue/resources such as the themes, migration to new styled mode is necessary.
  • switchTheme function, use the new APIs like usePreset instead to dynamic theme switching.
  • The legacy Tailwind preset at primevue/passthrough/tailwind, migrate to the Tailwind Presets project.

The team has put in a great effort to migrate the entire UI suite with minor breaking changes. Two components have been removed by design.

  • DataViewLayoutOptions is removed, use SelectButton instead as in the demo.
  • TriStateCheckbox is removed, use Checkbox with the new indeterminate state as a replacement.
  • Enhancements to internal structure of some components, see the tickets #5426 and #5437 for more information.