0
# Configuration & Theming
1

2
Global configuration, theme management, styling utilities, and PassThrough system for deep customization of PrimeVue components and application appearance.
3

4
## Capabilities
5

6
### Global Configuration
7

8
#### PrimeVue Config
9
Global configuration plugin for theme settings, locale, and component defaults.
10

11
```typescript { .api }
12
/**
13
 * PrimeVue global configuration
14
 */
15
import PrimeVue from "primevue/config";
16

17
interface PrimeVueConfiguration {
18
  ripple?: boolean;
19
  inputStyle?: "outlined" | "filled";
20
  locale?: Locale;
21
  filterMatchModeOptions?: object;
22
  zIndex?: {
23
    modal?: number;
24
    overlay?: number;
25
    menu?: number;
26
    tooltip?: number;
27
  };
28
  pt?: PassThroughOptions;
29
  ptOptions?: PassThroughGlobalOptions;
30
  unstyled?: boolean;
31
  csp?: {
32
    nonce?: string;
33
  };
34
}
35

36
// Vue 3 installation
37
app.use(PrimeVue, {
38
  ripple: true,
39
  inputStyle: 'outlined',
40
  locale: {
41
    startsWith: 'Starts with',
42
    contains: 'Contains',
43
    notContains: 'Not contains',
44
    endsWith: 'Ends with',
45
    equals: 'Equals',
46
    notEquals: 'Not equals'
47
  },
48
  pt: {
49
    button: {
50
      root: { class: 'my-button' }
51
    }
52
  }
53
});
54
```
55

56
### Theme System
57

58
#### Theme Installation
59
CSS theme files for different design systems and color schemes.
60

61
```typescript { .api }
62
/**
63
 * Theme CSS imports
64
 */
65
// Aura theme (default)
66
import "primevue/resources/themes/aura-light-green/theme.css";
67
import "primevue/resources/themes/aura-light-blue/theme.css";
68
import "primevue/resources/themes/aura-dark-green/theme.css";
69

70
// Material Design
71
import "primevue/resources/themes/md-light-indigo/theme.css";
72
import "primevue/resources/themes/md-dark-indigo/theme.css";
73

74
// Bootstrap
75
import "primevue/resources/themes/bootstrap4-light-blue/theme.css";
76
import "primevue/resources/themes/bootstrap4-dark-blue/theme.css";
77

78
// Core CSS (always required)
79
import "primevue/resources/primevue.min.css";
80

81
// Icons (optional)
82
import "primeicons/primeicons.css";
83
```
84

85
#### useStyle Composable
86
Composable for managing component styles and themes dynamically.
87

88
```typescript { .api }
89
/**
90
 * Style management composable
91
 */
92
import { useStyle } from "primevue/usestyle";
93

94
interface UseStyleOptions {
95
  name?: string;
96
  css?: string;
97
  load?: boolean;
98
  document?: Document;
99
  manual?: boolean;
100
  media?: string;
101
  nonce?: string;
102
  first?: boolean;
103
  props?: object;
104
}
105

106
interface UseStyleReturn {
107
  id: string;
108
  name: string;
109
  css: Ref<string>;
110
  load: () => void;
111
  unload: () => void;
112
  isLoaded: Readonly<Ref<boolean>>;
113
}
114

115
function useStyle(css: string, options?: UseStyleOptions): UseStyleReturn;
116
```
117

118
**Usage Example:**
119

120
```vue
121
<script setup>
122
import { useStyle } from 'primevue/usestyle';
123

124
const { load, unload } = useStyle(`
125
  .custom-button {
126
    background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
127
    border: none;
128
    color: white;
129
    padding: 12px 24px;
130
    border-radius: 8px;
131
  }
132
`, { name: 'custom-button' });
133

134
// Load styles
135
load();
136

137
// Unload when component unmounts
138
onUnmounted(() => {
139
  unload();
140
});
141
</script>
142
```
143

144
### PassThrough System
145

146
#### usePassThrough
147
Utility for merging PassThrough configurations for deep component customization.
148

149
```typescript { .api }
150
/**
151
 * PassThrough configuration merger
152
 */
153
import { usePassThrough } from "primevue/passthrough";
154

155
interface PassThroughOptions {
156
  mergeSections?: boolean;
157
  mergeProps?: boolean;
158
}
159

160
interface PassThroughGlobalOptions {
161
  mergeSections?: boolean;
162
  mergeProps?: boolean;
163
  useMergeProps?: boolean;
164
}
165

166
function usePassThrough(
167
  pt1: object, 
168
  pt2: object, 
169
  options?: PassThroughOptions
170
): object;
171
```
172

173
#### PassThrough Configuration
174
Comprehensive system for customizing component internals without CSS.
175

176
```typescript { .api }
177
/**
178
 * PassThrough configuration examples
179
 */
180

181
// Global PassThrough
182
app.use(PrimeVue, {
183
  pt: {
184
    button: {
185
      root: ({ props }) => ({
186
        class: [
187
          'px-4 py-2 rounded-lg',
188
          {
189
            'bg-blue-500 text-white': !props.outlined,
190
            'border border-blue-500 text-blue-500': props.outlined
191
          }
192
        ]
193
      }),
194
      label: { class: 'font-medium' }
195
    },
196
    inputtext: {
197
      root: { class: 'border-2 border-gray-300 rounded-md px-3 py-2' }
198
    }
199
  }
200
});
201

202
// Component-level PassThrough
203
// <Button :pt="{ root: { class: 'custom-button-class' } }" label="Custom" />
204

205
// Advanced PassThrough with functions
206
const buttonPT = {
207
  root: ({ props, state, context }) => ({
208
    class: [
209
      'p-button',
210
      {
211
        'p-button-loading': props.loading,
212
        'p-button-outlined': props.outlined,
213
        'p-button-raised': props.raised,
214
        'p-button-rounded': props.rounded,
215
        'p-button-text': props.text,
216
        'p-button-sm': props.size === 'small',
217
        'p-button-lg': props.size === 'large',
218
        'p-disabled': context.disabled
219
      },
220
      `p-button-${props.severity}`
221
    ],
222
    style: {
223
      transition: 'all 0.2s ease'
224
    }
225
  }),
226
  loadingIcon: { class: 'animate-spin' },
227
  icon: ({ props }) => ({
228
    class: [
229
      'p-button-icon',
230
      {
231
        'p-button-icon-left': props.iconPos === 'left',
232
        'p-button-icon-right': props.iconPos === 'right',
233
        'p-button-icon-top': props.iconPos === 'top',
234
        'p-button-icon-bottom': props.iconPos === 'bottom'
235
      }
236
    ]
237
  })
238
};
239
```
240

241
### Styling Approaches
242

243
#### Styled Mode (Default)
244
Pre-built themes with complete styling out of the box.
245

246
```typescript { .api }
247
/**
248
 * Styled mode configuration (default)
249
 */
250
// Import theme CSS
251
import "primevue/resources/themes/aura-light-green/theme.css";
252
import "primevue/resources/primevue.min.css";
253

254
// Components use pre-built styles
255
app.use(PrimeVue, {
256
  // Styled mode is default, no unstyled option needed
257
});
258
```
259

260
#### Unstyled Mode
261
Components without any styling for complete customization freedom.
262

263
```typescript { .api }
264
/**
265
 * Unstyled mode configuration
266
 */
267
app.use(PrimeVue, {
268
  unstyled: true,
269
  pt: {
270
    // Define all styles via PassThrough
271
    button: {
272
      root: 'bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded',
273
      label: 'select-none'
274
    }
275
  }
276
});
277
```
278

279
#### CSS Variables & Design Tokens
280
Customization through CSS custom properties and design tokens.
281

282
```css
283
/* Custom CSS variables for theme customization */
284
:root {
285
  --primary-color: #3B82F6;
286
  --primary-color-text: #ffffff;
287
  --surface-0: #ffffff;
288
  --surface-50: #f8fafc;
289
  --surface-100: #f1f5f9;
290
  --surface-200: #e2e8f0;
291
  --surface-300: #cbd5e1;
292
  --surface-400: #94a3b8;
293
  --surface-500: #64748b;
294
  --surface-600: #475569;
295
  --surface-700: #334155;
296
  --surface-800: #1e293b;
297
  --surface-900: #0f172a;
298
  
299
  --border-radius: 6px;
300
  --focus-ring: 0 0 0 2px #3B82F6;
301
  --mask-bg: rgba(0, 0, 0, 0.4);
302
}
303

304
/* Dark theme overrides */
305
[data-theme="dark"] {
306
  --primary-color: #60A5FA;
307
  --surface-0: #0f172a;
308
  --surface-50: #1e293b;
309
  --surface-100: #334155;
310
}
311
```
312

313
### Responsive Configuration
314

315
#### Breakpoint System
316
Responsive breakpoints for component behavior.
317

318
```typescript { .api }
319
/**
320
 * Responsive configuration
321
 */
322
const responsiveOptions = {
323
  breakpoints: {
324
    '1199px': {
325
      numVisible: 1,
326
      numScroll: 1
327
    },
328
    '991px': {
329
      numVisible: 2,
330
      numScroll: 1
331
    },
332
    '767px': {
333
      numVisible: 1,
334
      numScroll: 1
335
    }
336
  }
337
};
338

339
// Usage in components
340
// <Carousel :responsiveOptions="responsiveOptions" />
341
```
342

343
## Types
344

345
Configuration and theming type definitions:
346

347
```typescript { .api }
348
// Locale configuration
349
interface Locale {
350
  startsWith?: string;
351
  contains?: string;
352
  notContains?: string;
353
  endsWith?: string;
354
  equals?: string;
355
  notEquals?: string;
356
  noFilter?: string;
357
  filter?: string;
358
  lt?: string;
359
  lte?: string;
360
  gt?: string;
361
  gte?: string;
362
  dateIs?: string;
363
  dateIsNot?: string;
364
  dateBefore?: string;
365
  dateAfter?: string;
366
  clear?: string;
367
  apply?: string;
368
  matchAll?: string;
369
  matchAny?: string;
370
  addRule?: string;
371
  removeRule?: string;
372
  accept?: string;
373
  reject?: string;
374
  choose?: string;
375
  upload?: string;
376
  cancel?: string;
377
  completed?: string;
378
  pending?: string;
379
  fileSizeTypes?: string[];
380
  dayNames?: string[];
381
  dayNamesShort?: string[];
382
  dayNamesMin?: string[];
383
  monthNames?: string[];
384
  monthNamesShort?: string[];
385
  chooseYear?: string;
386
  chooseMonth?: string;
387
  chooseDate?: string;
388
  prevDecade?: string;
389
  nextDecade?: string;
390
  prevYear?: string;
391
  nextYear?: string;
392
  prevMonth?: string;
393
  nextMonth?: string;
394
  prevHour?: string;
395
  nextHour?: string;
396
  prevMinute?: string;
397
  nextMinute?: string;
398
  prevSecond?: string;
399
  nextSecond?: string;
400
  am?: string;
401
  pm?: string;
402
  today?: string;
403
  weekHeader?: string;
404
  firstDayOfWeek?: number;
405
  showMonthAfterYear?: boolean;
406
  dateFormat?: string;
407
  weak?: string;
408
  medium?: string;
409
  strong?: string;
410
  passwordPrompt?: string;
411
  emptyFilterMessage?: string;
412
  searchMessage?: string;
413
  selectionMessage?: string;
414
  emptySelectionMessage?: string;
415
  emptySearchMessage?: string;
416
  emptyMessage?: string;
417
  aria?: AriaLabels;
418
}
419

420
// ARIA labels for accessibility
421
interface AriaLabels {
422
  trueLabel?: string;
423
  falseLabel?: string;
424
  nullLabel?: string;
425
  star?: string;
426
  stars?: string;
427
  selectAll?: string;
428
  unselectAll?: string;
429
  close?: string;
430
  previous?: string;
431
  next?: string;
432
  navigation?: string;
433
  scrollTop?: string;
434
  moveTop?: string;
435
  moveUp?: string;
436
  moveDown?: string;
437
  moveBottom?: string;
438
  moveToTarget?: string;
439
  moveToSource?: string;
440
  moveAllToTarget?: string;
441
  moveAllToSource?: string;
442
  pageLabel?: string;
443
  firstPageLabel?: string;
444
  lastPageLabel?: string;
445
  nextPageLabel?: string;
446
  previousPageLabel?: string;
447
  rowsPerPageLabel?: string;
448
  jumpToPageDropdownLabel?: string;
449
  jumpToPageInputLabel?: string;
450
  selectRow?: string;
451
  unselectRow?: string;
452
  expandRow?: string;
453
  collapseRow?: string;
454
  showFilterMenu?: string;
455
  hideFilterMenu?: string;
456
  filterOperator?: string;
457
  filterConstraint?: string;
458
  editRow?: string;
459
  saveEdit?: string;
460
  cancelEdit?: string;
461
  listView?: string;
462
  gridView?: string;
463
  slide?: string;
464
  slideNumber?: string;
465
  zoomImage?: string;
466
  zoomIn?: string;
467
  zoomOut?: string;
468
  rotateRight?: string;
469
  rotateLeft?: string;
470
}
471
```