Arbitrary custom severities for Tag/Badge/Button/Message/InlineMessage/Toast

[sschalm]

Summary

Severity values are currently hardcoded across multiple components (primefaces/primeuix).
Requested: allow severity to be any string (for example pending, brand, help) without requiring project-level CSS workarounds.

Affected Components

• Tag (https://github.com/primefaces/primeuix/blob/main/packages/styles/src/tag/index.ts)
• Badge (https://github.com/primefaces/primeuix/blob/main/packages/styles/src/badge/index.ts)
• Button (https://github.com/primefaces/primeuix/blob/main/packages/styles/src/button/index.ts)
• Message (https://github.com/primefaces/primeuix/blob/main/packages/styles/src/message/index.ts)
• InlineMessage? => deprecated
• Toast (https://github.com/primefaces/primeuix/blob/main/packages/styles/src/toast/index.ts)

Current Behavior

• Only predefined severities are styled correctly.
• Custom severity names are not fully supported.
• Users need manual workaround CSS in their own projects.

Expected Behavior

• Severity should accept arbitrary values.
• Theme tokens for custom severities should be resolved directly.
• No manual custom class styling should be required in userland.

Technical Proposal

1. Dynamic severity rule generation in styles

Instead of only static CSS blocks for known severities, generate severity rules from available token keys.

Concept example:

.p-tag-pending {
background: dt('tag.pending.background');
color: dt('tag.pending.color');
}

Do the same pattern for Badge, Button, Message, InlineMessage, and Toast.

2. Open theme typing for custom keys

In the related design token types, keep built-in severity fields for IntelliSense and also allow arbitrary severity keys (for example via index signature), so TypeScript accepts custom severities without casts.

3. Widen component severity prop to string

In PrimeVue components, the severity prop should not be restricted to literal unions only; it should accept string.

severity: {
  type: String as PropType<'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'help' | 'danger' | 'contrast' | string>,
  default: null
}

Acceptance Criteria

• Existing built-in severities keep working unchanged.
• Custom severity works for all affected components.
• TypeScript accepts custom severity tokens without type-cast workarounds.
• No breaking changes for existing users.
• Documentation includes at least one custom severity example.

Example

Theme tokens:
Base:

import type { Primitive, MyPresetBaseDesignTokens, Semantic } from '../../../../../types/primevue/presets/myPreset/base'

export const primitive: Primitive = {
		...
} satisfies Primitive

export const semantic: Semantic = {
	transitionDuration: '0.2s',
	focusRing: {
		...
	},
	disabledOpacity: '0.6',
	iconSize: '1rem',
	anchorGutter: '2px',
	primary: {
		50: '{emerald.50}',
		100: '{emerald.100}',
		200: '{emerald.200}',
		300: '{emerald.300}',
		400: '{emerald.400}',
		500: '{emerald.500}',
		600: '{emerald.600}',
		700: '{emerald.700}',
		800: '{emerald.800}',
		900: '{emerald.900}',
		950: '{emerald.950}'
	},
	// awesome palettes for actual severities 😎
	secondary: {
		50: '{surface.50}',
		100: '{surface.100}',
		200: '{surface.200}',
		300: '{surface.300}',
		400: '{surface.400}',
		500: '{surface.500}',
		600: '{surface.600}',
		700: '{surface.700}',
		800: '{surface.800}',
		900: '{surface.900}',
		950: '{surface.950}'
	},
	info: {
		50: '{sky.50}',
		100: '{sky.100}',
		200: '{sky.200}',
		300: '{sky.300}',
		400: '{sky.400}',
		500: '{sky.500}',
		600: '{sky.600}',
		700: '{sky.700}',
		800: '{sky.800}',
		900: '{sky.900}',
		950: '{sky.950}'
	},
	success: {
		50: '{green.50}',
		100: '{green.100}',
		200: '{green.200}',
		300: '{green.300}',
		400: '{green.400}',
		500: '{green.500}',
		600: '{green.600}',
		700: '{green.700}',
		800: '{green.800}',
		900: '{green.900}',
		950: '{green.950}'
	},
	warn: {
		50: '{orange.50}',
		100: '{orange.100}',
		200: '{orange.200}',
		300: '{orange.300}',
		400: '{orange.400}',
		500: '{orange.500}',
		600: '{orange.600}',
		700: '{orange.700}',
		800: '{orange.800}',
		900: '{orange.900}',
		950: '{orange.950}'
	},
	help: {
		50: '{purple.50}',
		100: '{purple.100}',
		200: '{purple.200}',
		300: '{purple.300}',
		400: '{purple.400}',
		500: '{purple.500}',
		600: '{purple.600}',
		700: '{purple.700}',
		800: '{purple.800}',
		900: '{purple.900}',
		950: '{purple.950}'
	},
	danger: {
		50: '{red.50}',
		100: '{red.100}',
		200: '{red.200}',
		300: '{red.300}',
		400: '{red.400}',
		500: '{red.500}',
		600: '{red.600}',
		700: '{red.700}',
		800: '{red.800}',
		900: '{red.900}',
		950: '{red.950}'
	},
	// awesome custom severities 🎉
	pending: {
		50: '{warn.50}',
		100: '{warn.100}',
		200: '{warn.200}',
		300: '{warn.300}',
		400: '{warn.400}',
		500: '{warn.500}',
		600: '{warn.600}',
		700: '{warn.700}',
		800: '{warn.800}',
		900: '{warn.900}',
		950: '{warn.950}'
	},
	brand: {
		50: '{teal.50}',
		100: '{teal.100}',
		200: '{teal.200}',
		300: '{teal.300}',
		400: '{teal.400}',
		500: '{teal.500}',
		600: '{teal.600}',
		700: '{teal.700}',
		800: '{teal.800}',
		900: '{teal.900}',
		950: '{teal.950}'
	},
	formField: {
		...
	},
	list: {
		...
	},
	content: {
		borderRadius: '{border.radius.md}'
	},
	mask: {
		transitionDuration: '0.3s'
	},
	navigation: {
		...
	},
	overlay: {
		...
	},
	colorScheme: {
		light: {
			surface: {
				0: '#ffffff',
				50: '{slate.50}',
				100: '{slate.100}',
				200: '{slate.200}',
				300: '{slate.300}',
				400: '{slate.400}',
				500: '{slate.500}',
				600: '{slate.600}',
				700: '{slate.700}',
				800: '{slate.800}',
				900: '{slate.900}',
				950: '{slate.950}'
			},
			primary: {
				color: '{primary.500}',
				contrastColor: '#ffffff',
				hoverColor: '{primary.600}',
				activeColor: '{primary.700}'
			},
			// awesome palettes for actual severities 😎
			secondary: {
				color: '{secondary.500}',
				contrastColor: '#ffffff',
				hoverColor: '{secondary.600}',
				activeColor: '{secondary.700}'
			},
			info: {
				color: '{info.500}',
				contrastColor: '#ffffff',
				hoverColor: '{info.600}',
				activeColor: '{info.700}'
			},
			success: {
				color: '{success.500}',
				contrastColor: '#ffffff',
				hoverColor: '{success.600}',
				activeColor: '{success.700}'
			},
			warn: {
				color: '{warn.500}',
				contrastColor: '#ffffff',
				hoverColor: '{warn.600}',
				activeColor: '{warn.700}'
			},
			help: {
				color: '{help.500}',
				contrastColor: '#ffffff',
				hoverColor: '{help.600}',
				activeColor: '{help.700}'
			},
			danger: {
				color: '{danger.500}',
				contrastColor: '#ffffff',
				hoverColor: '{danger.600}',
				activeColor: '{danger.700}'
			},
			contrast: {
				color: '{surface.950}',
				contrastColor: '{surface.0}',
				hoverColor: '{surface.900}',
				activeColor: '{surface.800}'
			},
			// awesome custom severities 🎉
			pending: {
				color: '{pending.500}',
				contrastColor: '#ffffff',
				hoverColor: '{pending.600}',
				activeColor: '{pending.700}'
			},
			brand: {
				color: '{brand.500}',
				contrastColor: '#ffffff',
				hoverColor: '{brand.600}',
				activeColor: '{brand.700}'
			},
			...
		},
		dark: {
			surface: {
				0: '#ffffff',
				50: '{zinc.50}',
				100: '{zinc.100}',
				200: '{zinc.200}',
				300: '{zinc.300}',
				400: '{zinc.400}',
				500: '{zinc.500}',
				600: '{zinc.600}',
				700: '{zinc.700}',
				800: '{zinc.800}',
				900: '{zinc.900}',
				950: '{zinc.950}'
			},
			primary: {
				color: '{primary.400}',
				contrastColor: '{surface.900}',
				hoverColor: '{primary.300}',
				activeColor: '{primary.200}'
			},
			// awesome palettes for actual severities 😎
			secondary: {
				color: '{secondary.400}',
				contrastColor: '{surface.900}',
				hoverColor: '{secondary.300}',
				activeColor: '{secondary.200}'
			},
			info: {
				color: '{info.400}',
				contrastColor: '{info.950}',
				hoverColor: '{info.300}',
				activeColor: '{info.200}'
			},
			success: {
				color: '{success.400}',
				contrastColor: '{success.950}',
				hoverColor: '{success.300}',
				activeColor: '{success.200}'
			},
			warn: {
				color: '{warn.400}',
				contrastColor: '{warn.950}',
				hoverColor: '{warn.300}',
				activeColor: '{warn.200}'
			},
			help: {
				color: '{help.400}',
				contrastColor: '{help.950}',
				hoverColor: '{help.300}',
				activeColor: '{help.200}'
			},
			danger: {
				color: '{danger.400}',
				contrastColor: '{danger.950}',
				hoverColor: '{danger.300}',
				activeColor: '{danger.200}'
			},
			contrast: {
				color: '{surface.0}',
				contrastColor: '{surface.950}',
				hoverColor: '{surface.100}',
				activeColor: '{surface.200}'
			},
			// awesome custom severities 🎉
			pending: {
				color: '{pending.400}',
				contrastColor: '{pending.950}',
				hoverColor: '{pending.300}',
				activeColor: '{pending.200}'
			},
			brand: {
				color: '{brand.400}',
				contrastColor: '{brand.950}',
				hoverColor: '{brand.300}',
				activeColor: '{brand.200}'
			},
			...
		}
	}
} satisfies Semantic

export default {
	primitive,
	semantic
} satisfies MyPresetBaseDesignTokens

Tag component:

import type { TagDesignTokens, TagTokenSections } from '@primeuix/themes/types/tag'

export const root: TagTokenSections.Root = {
	fontSize: '0.875rem',
	fontWeight: '700',
	padding: '0.25rem 0.5rem',
	gap: '0.25rem',
	borderRadius: '{content.border.radius}',
	roundedBorderRadius: '{border.radius.xl}'
}

export const icon: TagTokenSections.Icon = {
	size: '0.75rem'
}

export const colorScheme: TagTokenSections.ColorScheme = {
	light: {
		primary: {
			background: '{primary.100}',
			color: '{primary.700}'
		},
		secondary: {
			background: '{secondary.100}',
			color: '{secondary.600}'
		},
		success: {
			background: '{success.100}',
			color: '{success.700}'
		},
		info: {
			background: '{info.100}',
			color: '{info.700}'
		},
		warn: {
			background: '{warn.100}',
			color: '{warn.700}'
		},
		// not possible see https://github.com/primefaces/primeuix/blob/main/packages/styles/src/tag/index.ts
		// see workaround in example! PrimevueTagExample.vue
		// help: {
		// 	background: '{help.100}',
		// 	color: '{help.700}'
		// },
		danger: {
			background: '{danger.100}',
			color: '{danger.700}'
		},
		contrast: {
			background: '{contrast.color}',
			color: '{contrast.contrast.color}'
		},
		// awesome custom severity
		pending: {
			background: '{warn.color}',
			color: '{warn.contrast.color}'
		}
	},
	dark: {
		primary: {
			background: 'color-mix(in srgb, {primary.500}, transparent 84%)',
			color: '{primary.300}'
		},
		secondary: {
			background: 'color-mix(in srgb, {secondary.500}, transparent 84%)',
			color: '{secondary.300}'
		},
		success: {
			background: 'color-mix(in srgb, {success.500}, transparent 84%)',
			color: '{success.300}'
		},
		info: {
			background: 'color-mix(in srgb, {info.500}, transparent 84%)',
			color: '{info.300}'
		},
		warn: {
			background: 'color-mix(in srgb, {warn.500}, transparent 84%)',
			color: '{warn.300}'
		},
		// not possible see https://github.com/primefaces/primeuix/blob/main/packages/styles/src/tag/index.ts
		// see workaround in example! PrimevueTagExample.vue
		// help: {
		// 	background: 'color-mix(in srgb, {help.500}, transparent 84%)',
		// 	color: '{help.300}'
		// },
		danger: {
			background: 'color-mix(in srgb, {danger.500}, transparent 84%)',
			color: '{danger.300}'
		},
		contrast: {
			background: '{contrast.color}',
			color: '{contrast.contrast.color}'
		},
		// awesome custom severity
		pending: {
			background: '{warn.color}',
			color: '{warn.contrast.color}'
		}
	}
}

export default {
	root,
	icon,
	colorScheme
} satisfies TagDesignTokens

Badge component:

import type { BadgeDesignTokens, BadgeTokenSections } from '@primeuix/themes/types/badge'

export const root: BadgeTokenSections.Root = {
	borderRadius: '{border.radius.md}',
	padding: '0 0.5rem',
	fontSize: '0.75rem',
	fontWeight: '700',
	minWidth: '1.5rem',
	height: '1.5rem'
}
export const dot: BadgeTokenSections.Dot = {
	size: '0.5rem'
}
export const sm: BadgeTokenSections.Sm = {
	fontSize: '0.625rem',
	minWidth: '1.25rem',
	height: '1.25rem'
}

export const lg: BadgeTokenSections.Lg = {
	fontSize: '0.875rem',
	minWidth: '1.75rem',
	height: '1.75rem'
}

export const xl: BadgeTokenSections.Xl = {
	fontSize: '1rem',
	minWidth: '2rem',
	height: '2rem'
}

export const colorScheme: BadgeTokenSections.ColorScheme = {
	light: {
		primary: {
			background: '{primary.color}',
			color: '{primary.contrast.color}'
		},
		secondary: {
			background: '{secondary.color}',
			color: '{secondary.contrast.color}'
		},
		success: {
			background: '{success.color}',
			color: '{success.contrast.color}'
		},
		info: {
			background: '{info.color}',
			color: '{info.contrast.color}'
		},
		warn: {
			background: '{warn.color}',
			color: '{warn.contrast.color}'
		},
		// not possible see https://github.com/primefaces/primeuix/blob/main/packages/styles/src/badge/index.ts
		// see workaround in example! PrimevueBadgeExample.vue
		// help: {
		// 	background: '{help.color}',
		// 	color: '{help.contrast.color}'
		// },
		danger: {
			background: '{danger.color}',
			color: '{danger.contrast.color}'
		},
		contrast: {
			background: '{contrast.color}',
			color: '{contrast.contrast.color}'
		}
		// awesome custom severity
		brand: {
			background: '{brand.color}',
			color: '{brand.contrast.color}'
		}
	},
	dark: {
		primary: {
			background: '{primary.color}',
			color: '{primary.contrast.color}'
		},
		secondary: {
			background: '{secondary.color}',
			color: '{secondary.contrast.color}'
		},
		success: {
			background: '{success.color}',
			color: '{success.contrast.color}'
		},
		info: {
			background: '{info.color}',
			color: '{info.contrast.color}'
		},
		warn: {
			background: '{warn.color}',
			color: '{warn.contrast.color}'
		},
		// not possible see https://github.com/primefaces/primeuix/blob/main/packages/styles/src/badge/index.ts
		// see workaround in example! PrimevueBadgeExample.vue
		// help: {
		// 	background: '{help.color}',
		// 	color: '{help.contrast.color}'
		// },
		danger: {
			background: '{danger.color}',
			color: '{danger.contrast.color}'
		},
		contrast: {
			background: '{contrast.color}',
			color: '{contrast.contrast.color}'
		},
		// awesome custom severity
		brand: {
			background: '{brand.color}',
			color: '{brand.contrast.color}'
		}
	}
}

export default {
	root,
	dot,
	sm,
	lg,
	xl,
	colorScheme
} satisfies BadgeDesignTokens

Usage:

<Tag severity="pending" value="Pending" />
<Badge severity="brand" value="New" />

Optional Follow-up

Similar issues:

• Toast: can't use custom severity primevue#7332
• Custom Severity support for Tag primevue#7567
• Inconsistent Severity Error vs Danger primevue#8268
• https://github.com/orgs/primefaces/discussions/3716

Workaround (primefaces/primevue#7567) only works for tag & badge!

There is currently a naming inconsistency (danger vs error) across components. (see primefaces/primevue#8268)
Optional improvement: unify naming or provide aliases (danger <-> error) to ease adoption.