PrimeNG Developer Guidelines

Pairs with angular-developer - that skill provides Angular fundamentals (signals, DI, routing, forms, SSR, accessibility). This skill focuses on PrimeNG specifics. Install both for the best experience.

Compatibility

• Tracks: PrimeNG 22.1.3 (released 2026-10-20), with @primeuix/themes and @primeuix/styles both 3.x (currently 3.0.2). PrimeNG follows Angular's major, so v22 requires Angular v22 (peer @angular/core@^22.1.0 from 22.1 on, ^22.0.0 on 22.0.x).
• Works for: PrimeNG v18 → v22 projects. The skill references include migration.md covering the v18 component renames (Calendar→DatePicker, Dropdown→Select, etc.) and the v21→v22 removals, so v18-v21 projects can use this skill but expect drift on theming and a few component APIs. v22 is the closest match.
• v21 → v22: v22 is an Angular-22 alignment plus @primeuix/themes/@primeuix/styles v3, and it finalizes (removes) the APIs that were deprecated "for removal in v22" in earlier versions, @primeng/themes import path, pTemplate, styleClass, showTransitionOptions/hideTransitionOptions, camelCase selectors, and the pButton icon/label props among them. Treat those as gone, not merely deprecated. See migration.md.
• v22.0 → v22.1: no breaking changes. 22.1 adds the experimental withIsolation() feature (primeng/isolation) for micro frontends and embedded widgets, filterMessage / selectionMessage / emptySelectionMessage inputs on p-select, a filteredNodes model on p-tree, and raises the Angular peer to ^22.1.0. Also remember v22 sizes components for a 16px root font; apps still on a 14px root should use the -compat presets (see theming.md). See migration.md.
• Docs domain: the official docs moved from primeng.org to primeng.dev (old links 301-redirect).
• Angular: v18 or newer required (v22 for PrimeNG v22). PrimeNG components are standalone since v18. The skill assumes standalone components, control flow (@if / @for), and signal-based APIs.
• Tailwind: v3 or v4 with tailwindcss-primeui plugin (optional, for unstyled mode).
• Not supported: PrimeNG v17 and below (different theming model based on prime.css), Angular v17 or below (NgModule patterns).

If the project's PrimeNG version is below v18, point the user to PrimeNG's v17 docs and decline to generate v18+ patterns into a v17 project, they will not compile.

1. Always check the project's PrimeNG version before providing guidance. PrimeNG v18 introduced major component renames (Calendar→DatePicker, Dropdown→Select, InputSwitch→ToggleSwitch, OverlayPanel→Popover, Sidebar→Drawer) and a new design-token theming system. package.json is the source of truth, when in doubt, look there before recommending an API. See migration.md.
2. Detect which theming mode the project uses before adding components:
   • If @primeuix/themes is imported and providePrimeNG({ theme: ... }) is configured → Styled mode (default).
   • If unstyled: true is set in providePrimeNG, or the project uses tailwindcss-primeui → Unstyled mode.
   • The two modes have fundamentally different customization paths. See styled-vs-unstyled.md.
3. Components are standalone since v18. Always import the standalone class (e.g. Button from 'primeng/button'), not the legacy *Module. Legacy modules still export for backwards compatibility but should not be added to new code.
4. After generating PrimeNG code, run ng build to catch compile errors. The most common AI mistakes are: (a) importing from @primeng/themes instead of @primeuix/themes (deprecated path); (b) forgetting provideAnimationsAsync() on v18 to v20 projects (PrimeNG v21+ uses native CSS animations and no longer requires it); (c) using v17 component names (Calendar, Dropdown, OverlayPanel, Sidebar, InputSwitch) after the v18 renames; (d) writing styleClass="…" on components, deprecated since v20, use native class="…" (or [class] / [ngClass]) instead; (e) writing pTemplate="item" inside a component imported standalone, the PrimeTemplate directive is NOT in scope unless you import SharedModule (or a *Module like TableModule that re-exports it), so the template silently never registers and the component renders empty rows with no build error and no console error. Use a template reference instead (<ng-template #item>, #content, #header, …), every v21 component content-queries those refs directly. See setup.md and migration.md.

PrimeNG architecture: Styled, Unstyled, PassThrough

PrimeNG ships compiled in node_modules, there is no source-copy CLI. Customization happens through three escalating mechanisms:

• Design tokens (Styled mode), override theme variables at the preset level via definePreset(Aura, {...}). Best for most theming needs. See theming.md.
• PassThrough (pt), per-component prop that injects classes/attributes into any internal DOM section. Works in both Styled and Unstyled modes. Use when tokens aren't enough. See passthrough.md.
• Unstyled mode, strip PrimeNG's styles entirely and provide your own (typically Tailwind via tailwindcss-primeui). Use for teams that already own a design system. See styled-vs-unstyled.md.

Default to Styled mode with Aura preset. Reach for PassThrough when you need to override specific internal sections. Reach for Unstyled only when the project is committed to a Tailwind-driven design system.

Installation and theming

• Setup: Install primeng @primeuix/themes @primeuix/styles, wire providePrimeNG() (and provideAnimationsAsync() on v18 to v20), common pitfalls. Read setup.md
• Theming: Aura / Lara / Nora / Material presets, design tokens, dark mode, definePreset overrides, runtime preset switching, CSS layer ordering. Read theming.md
• Styled vs Unstyled: When to use each mode, Tailwind v4 + tailwindcss-primeui integration, Volt UI reference patterns. Read styled-vs-unstyled.md
• PassThrough: The pt API, global pt in providePrimeNG, nested-component prefix (pcBadge), ptOptions.mergeSections and mergeProps. Read passthrough.md

Components

PrimeNG provides 80+ components grouped here by category. Each category file covers component APIs, common patterns, and gotchas.

• Form controls: AutoComplete, CascadeSelect, Checkbox, ColorPicker, DatePicker, Editor, FloatLabel, IconField, IftaLabel, InputMask, InputNumber, InputOtp, InputText, Knob, Listbox, MultiSelect, Password, RadioButton, Rating, Select, SelectButton, Slider, Textarea, ToggleButton, ToggleSwitch, TreeSelect. Read form-controls.md
• Buttons: Button, SpeedDial, SplitButton. Read buttons.md
• Overlays: ConfirmDialog, ConfirmPopup, Dialog, Drawer, DynamicDialog, Popover, Toast, Tooltip. Read overlays.md
• Layout: Accordion, BlockUI, Card, Divider, Fieldset, Panel, Scroller (VirtualScroller), ScrollTop, Splitter, Stepper, Tabs, Toolbar. Read layout.md
• Data display: Carousel, DataView, Galleria, OrderList, Paginator, PickList, Table, Timeline, Tree, TreeTable. Read data-display.md
• Display: Avatar, Badge, Chip, Image, Inplace, Message, MeterGroup, OverlayBadge, ProgressBar, ProgressSpinner, Ripple, Skeleton, Tag, Terminal. Read display.md
• Menus: Breadcrumb, ContextMenu, Dock, MegaMenu, Menu, MenuBar, PanelMenu, TieredMenu. Read menus.md

Forms integration

• Forms: Wiring PrimeNG form components to ReactiveForms or Signal Forms, the [invalid] prop (v20+) replacing .ng-invalid.ng-dirty, ControlValueAccessor patterns, validation display. Read forms.md

Accessibility

• Accessibility: WCAG 2.1 AA compliance built in, p-sr-only utility, ARIA conventions per component, keyboard navigation, focus management. Read accessibility.md

Migration

• Migration: v18 component renames (Calendar→DatePicker etc.), deprecated APIs, the [invalid] prop replacing .ng-invalid.ng-dirty, design-token system replacing the legacy SCSS theme. Read migration.md