CSS @font-palette-values At-Rule
The @font-palette-values at-rule defines custom color palettes for color fonts. It allows you to select an existing palette or replace individual colors within a font's palette, then apply the result using the font-palette property.
@font-palette-values Syntax
@font-palette-values --custom-palette {
font-family: "Color Font";
base-palette: 0;
override-colors: 0 #0066cc, 1 #ff9900;
}The at-rule begins with @font-palette-values, followed by a custom palette name and a declaration block.
The custom name begins with two hyphens. The font-family descriptor identifies the font family, while base-palette and override-colors control its colors.
The palette name is later assigned to an element using the font-palette property.
.color-heading {
font-family: "Color Font", sans-serif;
font-palette: --custom-palette;
}The name --custom-palette is a CSS dashed identifier, not a CSS custom property. It is used directly without the var() function.
How @font-palette-values Works
Some OpenType color fonts contain multiple colors within individual glyphs. These colors are stored in palettes defined by the font designer.
The @font-palette-values at-rule allows a stylesheet to customize those palettes without modifying the original font file.
The process involves defining a named palette, identifying the font family, optionally selecting a base palette, and overriding individual color entries as needed.
@font-palette-values --brand-colors {
font-family: "Color Font";
override-colors: 0 #0056b3, 1 #ff6600;
}
.brand-title {
font-family: "Color Font", sans-serif;
font-palette: --brand-colors;
}In this example, the browser uses the custom palette when rendering glyphs from the specified color font. The first two palette entries are replaced with the supplied colors.
The at-rule does not change ordinary monochrome fonts into color fonts. The selected font must contain compatible color glyph and palette information.
@font-palette-values Descriptors
Three main descriptors control a custom font palette.
| Descriptor | Description |
|---|---|
font-family |
Identifies the font family or families to which the palette applies. This descriptor is required. |
base-palette |
Selects an existing palette from the font using a numeric index, light, or dark. |
override-colors |
Replaces one or more colors in the selected palette using their zero-based indexes. |
The font-family descriptor must match the family name used when applying the font. The other descriptors are optional.
Without an explicit base-palette, the font's default palette is used as the starting point.
Selecting a Base Palette
The base-palette descriptor selects one of the palettes already defined inside a color font.
@font-palette-values --alternate-palette {
font-family: "Color Font";
base-palette: 2;
}Palette indexes begin at 0. The value 2 selects the third palette provided by the font.
The descriptor also accepts light and dark to request a palette designated by the font designer for a light or dark background.
@font-palette-values --dark-background {
font-family: "Color Font";
base-palette: dark;
}These keywords depend on palette metadata supplied by the font. They do not automatically change when the operating system switches color schemes.
If a requested numeric palette does not exist, the browser falls back to palette index 0.
Overriding Palette Colors
The override-colors descriptor replaces individual colors within a font palette.
@font-palette-values --custom-colors {
font-family: "Color Font";
base-palette: 0;
override-colors:
0 #e63946,
1 #457b9d,
2 #f4a261;
}Each entry contains a zero-based color index followed by a CSS color value. Entries are separated by commas.
In this example, the first three colors are replaced with red, blue, and orange shades.
Any palette entries not listed retain their original colors. An index that does not exist in the font's palette is ignored.
Hexadecimal colors, named colors, and CSS color functions can be used where supported.
Applying Custom Palettes
After defining a palette, use the font-palette property to apply it to an element.
@font-palette-values --blue-orange {
font-family: "Color Font";
override-colors: 0 #0066cc, 1 #ff9900;
}
.title-default {
font-family: "Color Font", sans-serif;
font-palette: normal;
}
.title-custom {
font-family: "Color Font", sans-serif;
font-palette: --blue-orange;
}The first heading uses the font's normal palette. The second requests the custom palette.
Different elements can use different palettes while sharing the same font family.
For glyphs whose colors come from the selected font palette, changing the ordinary color property does not replace those palette colors.
Font Requirements
The @font-palette-values at-rule is designed for color fonts with compatible palette information, such as OpenType fonts that use CPAL color palettes.
Before customizing a font, check whether it includes multiple palettes and which color indexes correspond to its glyph layers.
The at-rule does not load a font file. A downloadable color font can be defined separately using @font-face.
@font-face {
font-family: "Color Font";
src: url("fonts/color-font.woff2") format("woff2");
}
@font-palette-values --accent-palette {
font-family: "Color Font";
override-colors: 0 #0066cc;
}The font path is a placeholder. Replace it with a real color font containing the required palette information.
Not every color font format supports the same palette customization features. For example, fonts using embedded bitmap images may not expose colors that can be overridden through this at-rule.
@font-palette-values Example
The following example uses the Bungee Spice color font to compare its default colors with a custom palette.
<h2 class="default-title">Default Colors</h2>
<h2 class="custom-title">Custom Colors</h2>@import url("https://fonts.googleapis.com/css2?family=Bungee+Spice");
@font-palette-values --custom-colors {
font-family: "Bungee Spice";
override-colors: 0 #00ffbb, 1 #007744;
}
.default-title, .custom-title {
font-family: "Bungee Spice", fantasy;
font-size: 28px;
}
.custom-title {
font-palette: --custom-colors;
}The first heading displays the font's default palette. The second replaces two palette colors with shades of green.
This example requires the external font to load successfully. If it is unavailable, the fallback font may not display the palette differences.
Browser Support
The @font-palette-values at-rule is widely available in modern browsers. It has been supported across major browser engines since 2022. The visual result also depends on the color font's format and palette information. See Can I Use? for compatibility information.
Specifications
The @font-palette-values at-rule is defined in CSS Fonts Module Level 4. The specification describes custom font palettes and the descriptors used to select and override their colors.