Migration

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. Every component has been reviewed and enhanced. 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.cssa 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.

Names of some of the components have been changed to more common alternatives for example, Popover replaced OverlayPanel and InputSwitch is now called ToggleSwitch. Each component has been reviewed for a consistent naming between CSS class names and PT sections. An example would be the option element of a Select component that uses p-select-option for the class name.

Components have been utilized more within other components, for instance Dialog close button is not actually a PrimeVue button so that closeButtonProps can be used to enable the features of button like outlined, raised and more. Whenever a component is using another component, in v3 the pt sections were causing confusion, to prevent this pc prefix is added to indicate that the PT section is actually a PrimeVue component, not a simple DOM element. This is especially useful because PT allows passing arbitrary attributes to DOM elements whereas if the element is actually a PrimeVue component, props can also be passed.

Renamed Components

Old names are deprecated but still functional, migrate to new import paths instead e.g. primevue/calendar becomes primevue/datepicker.

• Calendar -> DatePicker.
• Dropdown -> Select.
• InputSwitch -> ToggleSwitch.
• OverlayPanel -> Popover.
• Sidebar -> Drawer.

Deprecated Components

Components that are deprecated since their functionality is provided by other components.

• Chips | Use AutoComplete with multiple enabled and typeahead disabled.
• TabMenu | Use Tabs without panels.
• Steps | Use Stepper without panels.
• InlineMessage | Use Message component.
• BadgeDirective | Use OverlayBadge instead.
• TabView | Use the new Tabs components.
• Accordion | Use with the new AccordionHeader and AccordionContent components.

Important Tickets

Issue tickets with detailed information about component internal changes.

• #5426
• #5437

SASS Themes

The styled mode theming has been reimplemented from scratch based on an all-new architecture. The theme.css and the primevue/resources do not exist anymore, so any imports of these assets needs to be removed. 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.

Removed Components

• TriStateCheckbox | Use Checkbox with indeterminate option.
• DataViewLayoutOptions | Use SelectButton instead.

Removed APIs

• switchTheme function, use the new APIs like usePreset instead to dynamic theme switching.

Removed Files

• Themes under the primevue/resources path, migration to new styled mode is necessary.
• The legacy Tailwind preset at primevue/passthrough/tailwind, migrate to the Tailwind Presets project.

Message and InlineMesasge

InlineMessage is deprecated due to overlap with the Message. The spacing, closable and life properties of the Message have breaking changes to provide InlineMessage functionality. Default margin is removed, closable is false by default and messages do not disappear automatically.

PT Section Names

The experimental PassThrough feature is not production ready, there are changes on the PT section names due to alignment with CSS classes for certain components. If when component element is another PrimeVue component pc prefix is added for indication. Review the Pass Through section of a component for the new API. The Tailwind CSS presets for the unstyled mode are not updated to v4 yet.

Removed Features

• Sidebar/Drawer size property is removed, use a responsive class utilty as replacement, demos have new examples.
• Rating cancel prop is removed as toggling the selected star value clears it.
• Inplace closable is removed in favor of templating and closeCallback prop.

Removed Style Classes

• .p-link, use a button in link mode.
• .p-highlight, each component have its own class such as .p-select-option-selected.
• .p-fluid, use the new built-in fluid properties of components.