harlan-zw/primevue-skilld

primefaces/primevue [email protected]

Tags: v2-stable: 2.10.4, v3-stable: 3.53.1, latest: 4.5.5

References: Docs

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: Calendar renamed to DatePicker — v3 component renamed to DatePicker in v4 source

• BREAKING: Dropdown renamed to Select — v3 component renamed to Select in v4 source

• BREAKING: Sidebar renamed to Drawer — v3 component renamed to Drawer in v4 source

• BREAKING: OverlayPanel renamed to Popover — v3 component renamed to Popover in v4 source

• BREAKING: InputSwitch renamed to ToggleSwitch — v3 component renamed to ToggleSwitch in v4 source

• BREAKING: TabView replaced by Tabs — new component structure using TabList, Tab, TabPanels, and TabPanel source

• BREAKING: Steps replaced by Stepper — new component structure using StepList, Step, StepPanels, and StepPanel source

• BREAKING: Accordion reimplementation — now uses AccordionPanel, AccordionHeader, and AccordionContent components source

• BREAKING: v-model:value — v4 uses v-model:value for active state in Tabs, Accordion, and Stepper instead of v-model source

• DEPRECATED: inputStyle — property replaced by inputVariant (values: 'filled' | 'outlined') source

• NEW: @primevue/forms — new dedicated package for advanced form management and validation source

• NEW: Fluid component — layout component that makes descendants span full width source

• NEW: IconField & InputIcon — new components to wrap inputs and icons for decorative purposes source

• NEW: useId & useAttrSelector — new core composables for unique ID generation and attribute selectors source

Also changed: DataTable showClearButton default is false (v4.3.0) · IftaLabel new component for in-field labels · Checkbox added indeterminate state · OverlayBadge new component replaces Badge directive · InlineMessage component deprecated · iconPosition removed from IconField · warning property renamed to warn · Drawer added before-hide emit (v4.3.0)

Best Practices

• Use the Fluid component as a wrapper for bulk application of full-width styles to inputs instead of adding the fluid prop to every individual field for cleaner and more maintainable templates source

<Fluid>
    <div class="grid grid-cols-2 gap-4">
        <InputText placeholder="Full Width" />
        <DatePicker placeholder="Full Width" />
        <Select placeholder="Full Width" />
    </div>
</Fluid>

• In Stepper vertical layouts, always wrap Step and StepPanel inside a StepItem component to ensure correct structure and connection between headers and content source

• Use asChild and v-slot on components like Step or Tab to implement headless mode for full UI control while retaining PrimeVue's built-in accessibility logic source

<Step v-slot="{ activateCallback, value, a11yAttrs }" asChild :value="1">
    <button @click="activateCallback" v-bind="a11yAttrs.header">
        Step {{ value }}
    </button>
</Step>

• For performant row expansion in DataTable with large datasets, use an object for expandedRows combined with dataKey instead of an array of row objects source

// Preferred (O(1) lookup)
const expandedRows = ref({ '1004': true, '1005': true });

// In template
<DataTable v-model:expandedRows="expandedRows" dataKey="id">

• Enable automatic user preference persistence (sorting, filtering, paging) in DataTable using stateStorage and stateKey to improve UX across page visits source

• Add a delay to VirtualScroller to throttle rendering during rapid scrolling, significantly improving UI responsiveness for extremely large lists source

<VirtualScroller :items="items" :itemSize="50" :delay="250">
    <template v-slot:item="{ item }">{{ item }}</template>
</VirtualScroller>

• Implement semantic navigation menus by using Tabs without TabPanels and combining it with router-link for accessible, state-aware top or side bars source

• Always wrap inputs and icons with IconField and InputIcon to ensure correct positioning and styling, supporting both leading and trailing icon placements source

<IconField>
    <InputIcon class="pi pi-search" />
    <InputText placeholder="Search" />
</IconField>

• Use IftaLabel for modern, top-aligned in-field labels that visually integrate with the input and handle validation states automatically source

• Leverage the built-in DataTable context menu integration to provide row-specific actions without manual event listener management or custom positioning logic source

<ContextMenu ref="cm" :model="menuModel" />
<DataTable :value="products" contextMenu @row-contextmenu="onRowContextMenu">