# Technical Documentation: mdn/content > ℹ️ **Provenance:** Hybrid Fusion: `mdn/content` + DevDocs `css` · [CodeWiki Reference](https://codewiki.google/github.com/mdn/content) · Recency: Active (< 180 days) ## 1. Repository Overview (mdn/content) # Welcome to MDN Web Docs [MDN Web Docs][] is an open-source, collaborative project that documents web technologies including CSS, HTML, JavaScript, and Web APIs. Alongside detailed reference documentation, we provide extensive learning resources for students and beginners getting started with web development. ## MDN's mission MDN's mission is to provide a blueprint for a better internet and empower a new generation of developers and content creators to build it. The strength of MDN Web Docs lies in its vast community of active readers and contributors. Since 2005, approximately 45,000 contributors have created the documentation we know and love. Together, contributors have created over 45,000 documents that make up an up-to-date, comprehensive, and free resource for web developers worldwide. In addition to English-language articles, over 35 volunteers lead translation and localization efforts for Chinese, French, Japanese, Korean, Portuguese, Russian, and Spanish. ## Build the site To set up the site locally, you need to have [Node.js](https://nodejs.org/) installed, which comes bundled with [npm](https://www.npmjs.com/). You can check if these are installed by running the following commands: ```bash node -v npm -v ``` After you have installed Node.js, you can install the dependencies using `npm install` and start the local preview: ```bash npm i npm start ``` Once started, a live preview is available at `http://localhost:5042/`. ## Contribute to MDN Web Docs You can contribute to MDN Web Docs and be a part of our community through content contributions, engineering, or translation work. The MDN Web Docs project welcomes contributions from everyone who shares our goals and wants to contribute constructively and respectfully within our community. To find out how to get started, see the [CONTRIBUTING.md](CONTRIBUTING.md) document in this repository. By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to our [Code of Conduct](CODE_OF_CONDUCT.md), which means adhering to [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). ## Get in touch You can communicate with the MDN Web Docs team and community using the [communication channels][]. [mdn web docs]: https://developer.mozilla.org [communication channels]: https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels ## 2. Official Technical Reference (DevDocs: CSS) # DevDocs Technical Reference: css > Source: DevDocs.io (css) | Formatted for AI Agents & Developers | Zero-Egress Edge Persistence ## Section: index # CSS reference Use this **CSS reference** to browse an [alphabetical index](#index) of all of the standard [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [properties](properties), [pseudo-classes](selectors/pseudo-classes), [pseudo-elements](selectors/pseudo-elements), [data types](values/data_types), [functional notations](values/functions) and [at-rules](at-rules). You can also browse [key CSS concepts](#concepts) and a list of [selectors organized by type](#selectors). Also included is a brief [DOM-CSS / CSSOM reference](#dom-css_cssom). ## Basic rule syntax ### Style rule syntax ``` style-rule ::= selectors-list { properties-list } ``` Where: ``` selectors-list ::= selector[:pseudo-class] [::pseudo-element] [, selectors-list] properties-list ::= [property : value] [; properties-list] ``` See the index of [*selectors*](#selectors), [*pseudo-classes*](#pseudo), and *[pseudo-elements](#pseudo)* below. The syntax for each specified *value* depends on the data type defined for each specified *property*. #### Style rule examples ``` strong { color: red; } div.menu-bar li:hover > ul { display: block; } ``` For a beginner-level introduction to the syntax of selectors, see our [guide on CSS Selectors](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors). Be aware that any [syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/Introduction) error in a rule definition invalidates the entire rule. Invalid rules are ignored by the browser. Note that CSS rule definitions are entirely (Unicode) [text-based](https://drafts.csswg.org/css-syntax/#intro), whereas DOM-CSS / CSSOM (the rule management system) is [object-based](https://drafts.csswg.org/cssom/#introduction). ### At-rule syntax As the structure of at-rules varies widely, please see [At-rule](at-rules) to find the syntax of the specific one you want. ## Index **Note:** This index does not include SVG-exclusive presentation attributes, which can be used as CSS properties on [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) elements. **Note:** The property names in this index do **not** include the JavaScript names which do differ from the CSS standard names. ## Selectors The following are the various [selectors](selectors), which allow styles to be conditional based on various features of elements within the DOM. ### Basic selectors **Basic selectors** are fundamental selectors; these are the most basic selectors that are frequently combined to create other, more complex selectors. - [Universal selector](selectors/universal_selectors) `*` - [Type selector](selectors/type_selectors) `elementname` - [Class selector](selectors/class_selectors) `.classname` - [ID selector](selectors/id_selectors) `#idname` - [Attribute selector](selectors/attribute_selectors) `[attr=value]` ### Grouping selectors [Selector list](selectors/selector_list) `A, B` Specifies that both `A` and `B` elements are selected. This is a grouping method to select several matching elements. ### Combinators Combinators are selectors that establish a relationship between two or more simple selectors, such as "`A` is a child of `B`" or "`A` is adjacent to `B`", creating a complex selector. [Next-sibling combinator](selectors/next-sibling_combinator) `A + B` Specifies that the elements selected by both `A` and `B` have the same parent and that the element selected by `B` immediately follows the element selected by `A` horizontally. [Subsequent-sibling combinator](selectors/subsequent-sibling_combinator) `A ~ B` Specifies that the elements selected by both `A` and `B` share the same parent and that the element selected by `A` comes before—but not necessarily immediately before—the element selected by `B`. [Child combinator](selectors/child_combinator) `A > B` Specifies that the element selected by `B` is the direct child of the element selected by `A`. [Descendant combinator](selectors/descendant_combinator) `A B` Specifies that the element selected by `B` is a descendant of the element selected by `A`, but is not necessarily a direct child. [Column combinator](selectors/column_combinator) `A || B` Experimental Specifies that the element selected by `B` is located within the table column specified by `A`. Elements which span multiple columns are considered to be a member of all of those columns. ### Pseudo [Pseudo classes](selectors/pseudo-classes) `:` Specifies a special state of the selected element(s). [Pseudo elements](selectors/pseudo-elements) `::` Represents entities that are not included in HTML. > [!CALLOUT] > > > > See also [selectors in the Selectors specification](https://drafts.csswg.org/selectors/) and the [pseudo-element specification](https://drafts.csswg.org/css-pseudo/). ## Concepts ### Syntax and semantics - [CSS syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/Introduction) - [At-rules](at-rules) - [Cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Introduction) - [Comments](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/Comments) - [Descriptor](https://developer.mozilla.org/en-US/docs/Glossary/CSS_Descriptor) - [Inheritance](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Inheritance) - [Shorthand properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties) - [Specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Specificity) - [Values](values) - [Value definition syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Values_and_units/Value_definition_syntax) - [CSS values and units](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Values_and_units) - [CSS functional notations](values/functions) ### Values - [Actual value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#actual_value) - [Computed value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#computed_value) - [Initial value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#initial_value) - [Resolved value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#resolved_value) - [Specified value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#specified_value) - [Used value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#used_value) ### Layout - [Block formatting context](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Display/Block_formatting_context) - [Box model](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Box_model/Introduction) - [Containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Display/Containing_block) - [Layout mode](https://developer.mozilla.org/en-US/docs/Glossary/Layout_mode) - [Margin collapsing](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Box_model/Margin_collapsing) - [Replaced elements](https://developer.mozilla.org/en-US/docs/Glossary/Replaced_elements) - [Stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Positioned_layout/Stacking_context) - [Visual formatting model](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Display/Visual_formatting_model) ## DOM-CSS / CSSOM ### Major object types - [`Document.styleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/Document/styleSheets) - [`HTMLElement.style`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) - [`Element.className`](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) - [`Element.classList`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) - [`StyleSheetList`](https://developer.mozilla.org/en-US/docs/Web/API/StyleSheetList) - [`CSSRuleList`](https://developer.mozilla.org/en-US/docs/Web/API/CSSRuleList) - [`CSSRule`](https://developer.mozilla.org/en-US/docs/Web/API/CSSRule) - [`CSSStyleRule`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleRule) - [`CSSStyleDeclaration`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration) ### Important methods - [`CSSStyleSheet.insertRule()`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/insertRule) - [`CSSStyleSheet.deleteRule()`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/deleteRule) ## See also - [Mozilla CSS extensions](mozilla_extensions) (prefixed with `-moz-`) - [WebKit CSS extensions](webkit_extensions) (mostly prefixed with `-webkit-`) ## External Links - [CSS Indices (w3.org)](https://www.w3.org/TR/css/#indices) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) --- ## Section: at-rules/@media/color-index # `color-index` CSS media feature Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since July 2015. The **`color-index`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [media feature](../@media#media_features) can be used to test the number of entries in the output device's color lookup table. ## Syntax The `color-index` feature is specified as an [``](../../values/integer) value representing the number of entries in the output device's color lookup table. (This value is zero if the device does not use such a table.) It is a range feature, meaning that you can also use the prefixed **`min-color-index`** and **`max-color-index`** variants to query minimum and maximum values, respectively. ## Examples ### Basic example #### HTML ``` This is a test. ``` #### CSS ``` p { color: black; } @media (color-index) { p { color: red; } } @media (min-color-index: 15000) { p { color: #1475ef; } } ``` #### Result ### Custom stylesheet This HTML will apply a special stylesheet for devices that have at least 256 colors. ``` - = 256)" href="https://cdn.example.com/color-stylesheet.css" /> ``` ## Specifications | Specification | | --- | | Media Queries Level 4 # color-index | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `color-index` | 29 | 79 | No | 16 | 8 | 29 | No | 16 | 8 | 2.0 | 4.4 | 8 | ## See also [Using Media Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries/Using) - [@media](../@media) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/color-index](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/color-index) --- ## Section: properties/z-index # `z-index` CSS property Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since July 2015. The **`z-index`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) property sets the z-order of a [positioned](position) element and its descendants or flex and grid items. Overlapping elements with a larger z-index cover those with a smaller one. ## Try it ``` z-index: auto; ``` ``` z-index: 1; ``` ``` z-index: 3; ``` ``` z-index: 5; ``` ``` z-index: 7; ``` ``` Change my z-index z-index: 6 z-index: 4 z-index: 2 z-index: auto z-index: auto z-index: auto ``` ``` #example-element { top: 15px; left: 15px; width: 180px; height: 230px; position: absolute; /* center the text so it is visible even when z-index is set to auto */ line-height: 215px; font-family: monospace; background-color: #fcfbe5; border: solid 5px #e3e0a1; z-index: auto; color: black; } .container { display: inline-block; width: 250px; position: relative; } .block { width: 150px; height: 50px; position: absolute; font-family: monospace; color: black; } .blue { background-color: #e5e8fc; border: solid 5px #112382; /* move text to the bottom of the box */ line-height: 55px; } .red { background-color: #fce5e7; border: solid 5px #e3a1a7; } .position1 { top: 0; left: 0; z-index: 6; } .position2 { top: 30px; left: 30px; z-index: 4; } .position3 { top: 60px; left: 60px; z-index: 2; } .position4 { top: 150px; left: 0; z-index: auto; } .position5 { top: 180px; left: 30px; z-index: auto; } .position6 { top: 210px; left: 60px; z-index: auto; } ``` For a positioned box (that is, one with any `position` other than `static`), the `z-index` property specifies: - The stack level of the box in the current [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Positioned_layout/Stacking_context). - Whether the box establishes a local stacking context. ## Syntax ``` /* Keyword value */ z-index: auto; /* values */ z-index: 0; z-index: 3; z-index: 289; z-index: -1; /* Negative values to lower the priority */ /* Global values */ z-index: inherit; z-index: initial; z-index: revert; z-index: revert-layer; z-index: unset; ``` ### Values This property is specified as one of the following values: [`auto`](#auto) The box does not establish a new local stacking context. The stack level of the generated box in the current stacking context is `0`. [``](#<integer>) This [``](../values/integer) is the stack level of the generated box in the current stacking context. The box also establishes a local stacking context. This means that the z-indexes of descendants are not compared to the z-indexes of elements outside this element. ## Formal definition | Initial value | auto | | --- | --- | | Applies to | positioned elements | | Inherited | no | | Computed value | as specified | | Animation type | an <a href="/en-US/docs/Web/CSS/Reference/Values/integer#interpolation" title="Values of the <integer> CSS data type are interpolated via integer discrete steps. The calculation is done as if they were real, floating-point numbers and the discrete value is obtained using the floor function.">integer</a> | ## Formal syntax ``` z-index = auto | = ``` ## Examples ### Visually layering elements #### HTML ``` Dashed box Gold box Green box ``` #### CSS ``` .wrapper { position: relative; } .dashed-box { position: relative; z-index: 1; border: dashed; height: 8em; margin-bottom: 1em; margin-top: 2em; } .gold-box { position: absolute; z-index: 3; /* put .gold-box above .green-box and .dashed-box */ background: gold; width: 80%; left: 60px; top: 3em; } .green-box { position: absolute; z-index: 2; /* put .green-box above .dashed-box */ background: lightgreen; width: 20%; left: 65%; top: -25px; height: 7em; opacity: 0.9; } ``` #### Result ## Specifications | Specification | | --- | | Cascading Style Sheets Level 2 # z-index | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `z-index` | 1 | 12 | 1 | 4 | 1 | 18 | 4 | 14 | 1 | 1.0 | 4.4 | 1 | | `auto` | 1 | 12 | 1 | 15 | 1 | 18 | 4 | 14 | 1 | 1.0 | 4.4 | 1 | | `negative_values` | 1 | 12 | 3 | 4 | 1 | 18 | 4 | 14 | 1 | 1.0 | 4.4 | 1 | ## See also - CSS [`position`](position) property - [Understanding CSS z-indexes](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Positioned_layout/Understanding_z-index) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/z-index) --- ## Section: values/sibling-index # `sibling-index()` CSS function Baseline Newly available This feature works across the latest devices and browser versions. This feature might not work in older devices or browser versions. It's been available across browsers since August 2026. The **`sibling-index()`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [function](functions) returns an integer representing the position of the current element in the DOM tree relative to all its sibling elements. The returned value is the index number of the contextual child's position among all the sibling elements within a parent element, with the first child returning `1` and the last child, returning the `length` of [`Element.children`](https://developer.mozilla.org/en-US/docs/Web/API/Element/children). **Note:** Like the [`:nth-child()`](../selectors/:nth-child) pseudo-class, `sibling-index()` starts from 1, not 0. **Note:** The [`counter()`](counter) function provides a similar result but it returns a `` (which is more suitable for [generated content](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Generated_content), while `sibling-index()` returns an `` (which can be used for calculations). ## Try it ``` --width: calc(sibling-index() * 30px); ``` ``` --width: calc(sibling-index() * 20px); ``` ``` --width: calc(sibling-index() * 10px); ``` ``` --width: 100px; ``` ``` - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 ``` ``` #example-element { list-style-type: none; padding: 0; margin: 0 auto; display: flex; flex-direction: column; align-items: center; gap: 4px; } #example-element > li { text-align: center; padding: 2px; border-radius: 8px; width: var(--width, calc(sibling-index() * 30px)); color: white; background-color: hsl( calc(360deg / sibling-count() * sibling-index()) 50% 50% ); } ``` ## Syntax ``` sibling-index() ``` ### Parameters The `sibling-index()` function doesn't accept parameters. ### Return value An integer; the position of the current element in the DOM tree's sibling order. ## Examples ### Dynamic list width This example demonstrates how to dynamically increase the width of each [`- `](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) item in the ` ` by `50px`. #### HTML ``` One - Two - Three - Four ``` #### CSS ``` li { width: calc(sibling-index() * 50px); background-color: #ffaaaa; } ``` #### Results ### Sequential animations Combining `sibling-index()` with CSS animations opens new possibilities. In this example, the opacity of elements in sequential order by setting an [`animation-delay`](../properties/animation-delay) based on their order in the DOM. #### HTML We include a container element with four children: ``` - One - Two - Three - Four ``` #### CSS We apply the `fade-in` animation to each element. We use the `sibling-index()` function within a [`calc()`](calc) function to set the duration of the `animation-delay` based on the source element's position in the source order. The [`animation-fill-mode`](../properties/animation-fill-mode) applies the animation's `0%` keyframe until the `animation-duration` expires. ``` ul { list-style-type: none; padding: 0; margin: 0; } li { animation-name: fade-in; animation-duration: 1s; animation-iteration-count: 1; animation-timing-function: linear; animation-fill-mode: backwards; animation-delay: calc(1s * sibling-index()); } @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } } ``` #### Results ## Specifications | Specification | | --- | | CSS Values and Units Module Level 5 # funcdef-sibling-index | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `sibling-index` | 138 | 138 | 154 | 122 | 26.2 | 138 | 154 | 91 | 26.2 | 30.0 | 138 | 26.2 | ## See also - [`sibling-count()`](sibling-count) - [`counter()`](counter) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/sibling-index](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/sibling-index) --- ## Section: at-rules # CSS at-rules **At-rules** are [CSS statements](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/Introduction#css_statements) that instruct CSS how to behave. They are used to group and structure style rules and other at-rules, declare style information not directly associated with selected content, and manage syntactic constructs such as imports and namespaces keyword mappings. They begin with an at-sign, `@` (U+0040 COMMERCIAL AT), followed by an identifier. ## Index of at-rules and at-rule descriptors - [`@charset`](at-rules/@charset) - [`@color-profile`](at-rules/@color-profile) - [`@container`](at-rules/@container) - [`@counter-style`](at-rules/@counter-style) [`additive-symbols`](at-rules/@counter-style/additive-symbols) - [`fallback`](at-rules/@counter-style/fallback) - [`negative`](at-rules/@counter-style/negative) - [`pad`](at-rules/@counter-style/pad) - [`prefix`](at-rules/@counter-style/prefix) - [`range`](at-rules/@counter-style/range) - [`speak-as`](at-rules/@counter-style/speak-as) - [`suffix`](at-rules/@counter-style/suffix) - [`symbols`](at-rules/@counter-style/symbols) - [`system`](at-rules/@counter-style/system) - [`@custom-media`](at-rules/@custom-media) - [`@document`](at-rules/@document) Non-standard Deprecated - [`@font-face`](at-rules/@font-face) [`ascent-override`](at-rules/@font-face/ascent-override) - [`descent-override`](at-rules/@font-face/descent-override) - [`font-display`](at-rules/@font-face/font-display) - [`font-family`](at-rules/@font-face/font-family) - [`font-feature-settings`](at-rules/@font-face/font-feature-settings) - [`font-stretch`](at-rules/@font-face/font-stretch) - [`font-style`](at-rules/@font-face/font-style) - [`font-variation-settings`](at-rules/@font-face/font-variation-settings) - [`font-weight`](at-rules/@font-face/font-weight) - [`line-gap-override`](at-rules/@font-face/line-gap-override) - [`size-adjust`](at-rules/@font-face/size-adjust) - [`src`](at-rules/@font-face/src) - [`unicode-range`](at-rules/@font-face/unicode-range) - [`@font-feature-values`](at-rules/@font-feature-values) [`font-display`](at-rules/@font-feature-values/font-display) - [`@font-palette-values`](at-rules/@font-palette-values) [`base-palette`](at-rules/@font-palette-values/base-palette) - [`font-family`](at-rules/@font-palette-values/font-family) - [`override-colors`](at-rules/@font-palette-values/override-colors) - [`@function`](at-rules/@function) Experimental - [`@import`](at-rules/@import) - [`@keyframes`](at-rules/@keyframes) - [`@layer`](at-rules/@layer) - [`@media`](at-rules/@media) (see [list of media features](#index_of_media_features) in the next section) - [`@namespace`](at-rules/@namespace) - [`@page`](at-rules/@page) [`page-orientation`](at-rules/@page/page-orientation) - [`size`](at-rules/@page/size) - [`@position-try`](at-rules/@position-try) - [`@property`](at-rules/@property) [`inherits`](at-rules/@property/inherits) - [`initial-value`](at-rules/@property/initial-value) - [`syntax`](at-rules/@property/syntax) - [`@scope`](at-rules/@scope) - [`@starting-style`](at-rules/@starting-style) - [`@supports`](at-rules/@supports) - [`@view-transition`](at-rules/@view-transition) ## Index of media features - [`-moz-device-pixel-ratio`](at-rules/@media/-moz-device-pixel-ratio) - [`-webkit-animation`](at-rules/@media/-webkit-animation) - [`-webkit-device-pixel-ratio`](at-rules/@media/-webkit-device-pixel-ratio) - [`-webkit-transform-2d`](at-rules/@media/-webkit-transform-2d) - [`-webkit-transform-3d`](at-rules/@media/-webkit-transform-3d) - [`-webkit-transition`](at-rules/@media/-webkit-transition) - [`any-hover`](at-rules/@media/any-hover) - [`any-pointer`](at-rules/@media/any-pointer) - [`aspect-ratio`](at-rules/@media/aspect-ratio) - [`color`](at-rules/@media/color) - [`color-gamut`](at-rules/@media/color-gamut) - [`color-index`](at-rules/@media/color-index) - [`device-aspect-ratio`](at-rules/@media/device-aspect-ratio) - [`device-height`](at-rules/@media/device-height) - [`display-mode`](at-rules/@media/display-mode) - [`dynamic-range`](at-rules/@media/dynamic-range) - [`forced-colors`](at-rules/@media/forced-colors) - [`grid`](at-rules/@media/grid) - [`height`](at-rules/@media/height) - [`horizontal-viewport-segments`](at-rules/@media/horizontal-viewport-segments) - [`hover`](at-rules/@media/hover) - [`inverted-colors`](at-rules/@media/inverted-colors) - [`monochrome`](at-rules/@media/monochrome) - [`orientation`](at-rules/@media/orientation) - [`overflow-block`](at-rules/@media/overflow-block) - [`overflow-inline`](at-rules/@media/overflow-inline) - [`pointer`](at-rules/@media/pointer) - [`prefers-color-scheme`](at-rules/@media/prefers-color-scheme) - [`prefers-contrast`](at-rules/@media/prefers-contrast) - [`prefers-reduced-data`](at-rules/@media/prefers-reduced-data) - [`prefers-reduced-motion`](at-rules/@media/prefers-reduced-motion) - [`prefers-reduced-transparency`](at-rules/@media/prefers-reduced-transparency) - [`resolution`](at-rules/@media/resolution) - [`scan`](at-rules/@media/scan) - [`scripting`](at-rules/@media/scripting) - [`shape`](at-rules/@media/shape) - [`update`](at-rules/@media/update) - [`vertical-viewport-segments`](at-rules/@media/vertical-viewport-segments) - [`video-dynamic-range`](at-rules/@media/video-dynamic-range) - [`width`](at-rules/@media/width) ## Specifications | Specification | | --- | | [CSS Syntax Module Level 3](https://drafts.csswg.org/css-syntax/) | ## See also - [CSS at-rule functions](at-rules/at-rule_functions) - [Nesting at-rules](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Nesting/At-rules) - [CSS syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax) module - [CSS conditional rules](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules) --- ## Section: at-rules/@charset # `@charset` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since July 2015. The **`@charset`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) rule specifies the character encoding used in the style sheet. This syntax is useful when using non-[ASCII](https://developer.mozilla.org/en-US/docs/Glossary/ASCII) characters in some CSS properties, like [`content`](../properties/content). Although the first character in `@charset` is the `@` symbol, it is not an [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules). It is a specific byte sequence that can only be placed at the very beginning of a stylesheet. No other characters, except the Unicode byte-order mark, are allowed before it. It also does not follow normal CSS syntax rules such as use of quotes or whitespace. If a `@charset` is not recognized as the charset declaration, it is parsed as a normal at-rule. The [CSS syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax) module deprecates this fallback behavior, defining it as an unrecognized legacy rule to be dropped when a stylesheet is grammar-checked. As there are several ways to define the character encoding of a style sheet, the browser will try the following methods in the following order (and stop as soon as one yields a result): - The value of the [Unicode byte-order](https://en.wikipedia.org/wiki/Byte_order_mark) character placed at the beginning of the file. - The value given by the `charset` attribute of the `Content-Type:` HTTP header or the equivalent in the protocol used to serve the style sheet. - The `@charset` CSS declaration. - Use the character encoding defined by the referring document: the `charset` attribute of the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element. This method is obsolete and should not be used. - Assume that the document is UTF-8. ## Syntax ``` @charset "UTF-8"; @charset "iso-8859-15"; ``` ### Parameters [*charset*](#charset) A [``](../values/string) denoting the character encoding to be used. It must be the name of a web-safe character encoding defined in the [IANA-registry](https://www.iana.org/assignments/character-sets/character-sets.xhtml), and must be double-quoted, following exactly one space character (U+0020), and immediately terminated with a semicolon. If several names are associated with an encoding, only the one marked with *preferred* must be used. ## Formal syntax Note that the `@charset` rule is not parsed via syntax, but via a specific byte sequence of the following form: ``` @charset ""; ``` ## Examples ### Valid and invalid charset declarations ``` @charset "UTF-8"; /* Set the encoding of the style sheet to Unicode UTF-8 */ ``` ``` @charset 'iso-8859-15'; /* Invalid, wrong quotes used */ @charset "UTF-8"; /* Invalid, more than one space */ @charset "UTF-8"; /* Invalid, there is a character (a space) before the declarations */ @charset UTF-8; /* Invalid, the charset is a CSS and requires double-quotes */ ``` ## Specifications | Specification | | --- | | CSS Syntax Module Level 3 # at-ruledef-charset | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `charset` | 2 | 12 | 1.5Firefox 1 supported an invalid syntax where the character encoding is not between single or double quotes. | 9 | 4 | 18 | 4 | 10.1 | 4 | 1.0 | 2 | 4 | ## See also - [Character set](https://developer.mozilla.org/en-US/docs/Glossary/Character_set) glossary entry - [Unicode](https://developer.mozilla.org/en-US/docs/Glossary/Unicode) glossary entry © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@charset](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@charset) --- ## Section: at-rules/@color-profile # `@color-profile` CSS at-rule The **`@color-profile`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) defines and names a color profile which can later be used in the [`color()`](../values/color_value/color) function to specify a color. ## Syntax ``` @color-profile --swop5c { src: url("https://example.org/SWOP2006_Coated5v2.icc"); } ``` ### Parameters profile name Either a [``](../values/dashed-ident) or the identifier `device-cmyk`. ### Descriptors [`src`](#src) Specifies the URL to retrieve the color-profile information from. [`rendering-intent`](#rendering-intent) If the color profile contains more than one rendering intent, this descriptor allows one to be selected as the one to use to define how to map the color to smaller [gamut](https://developer.mozilla.org/en-US/docs/Glossary/gamut)s than this profile is defined over. If used, it must be one of the following keywords: [`relative-colorimetric`](#relative-colorimetric) Media-relative colorimetric is required to leave source colors that fall inside the destination medium [gamut](https://developer.mozilla.org/en-US/docs/Glossary/gamut) unchanged relative to the respective media white points. Source colors that are out of the destination medium gamut are mapped to colors on the gamut boundary using a variety of different methods. [`absolute-colorimetric`](#absolute-colorimetric) ICC-absolute colorimetric is required to leave source colors that fall inside the destination medium [gamut](https://developer.mozilla.org/en-US/docs/Glossary/gamut) unchanged relative to the adopted white (a perfect reflecting diffuser). Source colors that are out of the destination medium gamut are mapped to colors on the gamut boundary using a variety of different methods. [`perceptual`](#perceptual) This method is often the preferred choice for images, especially when there are substantial differences between the source and destination (such as a screen display image reproduced on a reflection print). It takes the colors of the source image and re-optimizes the appearance for the destination medium using proprietary methods. [`saturation`](#saturation) This option was created to preserve the relative saturation (chroma) of the original, and to keep solid colors pure. However, it experienced interoperability problems like the perceptual intent. ## Formal syntax ## Examples This example demonstrates using offset printing to ISO 12647-2:2004 using the CGATS/SWOP TR005 2007 characterization data on grade 5 paper with an ink limit of 300% Total Area Coverage, and medium gray component replacement (GCR). This example is from the specification. The `src` descriptor specifies the URL to retrieve the color-profile information from. ``` @color-profile --swop5c { src: url("https://example.org/SWOP2006_Coated5v2.icc"); } .header { background-color: color(--swop5c 0% 70% 20% 0%); } ``` ## Specifications | Specification | | --- | | CSS Color Module Level 5 # at-profile | ## Browser compatibility Currently, no browsers support this feature. ## See also - [CSS colors](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Colors) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@color-profile](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@color-profile) --- ## Section: at-rules/@container # `@container` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since February 2023. The **`@container`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) is a conditional group rule that applies styles to a [containment context](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries#naming_containment_contexts). Style declarations are filtered by a condition and applied to the elements within the container if the condition is true. The condition is evaluated when the queried container size, [``](#container_style_queries), or scroll-state changes. The condition must specify a [`container-name`](../properties/container-name), and ``, or both. The [`container-name`](../properties/container-name) property specifies a list of query container names, which are used to filter which containers are targeted by the `@container` rules. If only a `container-name` value is included (a [name-only container query](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries#name-only_container_queries)), the contained rules are applied to any containers with one or more of those `container-name` values set on them. The container features in the `` are evaluated against the selected containers. If no `` is specified, the `` features are evaluated against the nearest ancestor query container that has the matching [`container-type`](../properties/container-type). ## Syntax ``` /* With a */ @container (width > 400px) { h2 { font-size: 1.5em; } } /* With an optional */ @container tall (height > 30rem) { p { line-height: 1.6; } } /* With a only (query is optional) */ @container sidebar { h2 { background: blue; } } /* With a */ @container scroll-state(scrollable: top) { .back-to-top-link { visibility: visible; } } /* With an anchored query */ @container anchored(fallback: bottom) { .infobox::before { content: "▲"; bottom: 100%; top: auto; } } /* With a and a */ @container sticky-heading scroll-state(stuck: top) { h2 { background: purple; color: white; } } /* Multiple queries in a single condition */ @container (width > 400px) and style(--responsive: true) { h2 { font-size: 1.5em; } } /* Condition list */ @container card (width > 400px), style(--responsive: true), scroll-state(stuck: top) { h2 { font-size: 1.5em; } } /* Boolean style() queries */ @container style(--theme: one) or style(--theme: two) { /* matched container styles */ } @container style((--theme: one) or (--theme: two)) { /* matched container styles */ } @container style(--theme: one) and style(--theme: two) { /* matched container styles */ } @container style((--theme: one) and (--theme: two)) { /* matched container styles */ } @container not style(--theme: one) { /* matched container styles */ } /* range style() queries */ @container style(--number > 4) { /* matched container styles */ } ``` ### Parameters [``](#<container-condition>) One or both of `` and ``. Styles defined in the `` are applied if the condition is `true`. [``](#<container-name>) Optional The name of the container to query; it is specified as an [``](../values/ident). If the query evaluates to `true`, the declared styles are applied to the container's descendant elements. [``](#<container-query>) Optional A set of features that are evaluated against the query container when the size, [``](#container_style_queries), scroll-state, or applied position-try fallback of the container changes. ### Logical keywords in container queries Logical keywords can be used to define the container condition: - `and` combines two or more conditions. - `or` combines two or more conditions. - `not` negates the condition. Only one `not` condition is allowed per container query and it cannot be used with the `and` or `or` keywords. ``` @container (width > 400px) and (height > 400px) { /* */ } @container (width > 400px) or (height > 400px) { /* */ } @container not (width < 400px) { /* */ } ``` ### Named containment contexts A containment context can be named using the [`container-name`](../properties/container-name) property. ``` .post { container-name: sidebar; container-type: inline-size; } ``` The shorthand syntax for this is to use [`container`](../properties/container) in the form `container: / `, for example: ``` .post { container: sidebar / inline-size; } ``` In container queries, the [`container-name`](../properties/container-name) property is used to filter the set of containers to those with a matching query container name: ``` @container sidebar (width > 400px) { /* */ } ``` Details about usage and naming restrictions are described in the [`container-name`](../properties/container-name) page. ### Descriptors The `` queries include [size](#size_container_descriptors), [scroll-state](#scroll-state_container_descriptors), and [anchored](#anchored_container_descriptors) container descriptors. #### Size container descriptors The `` can include one or more boolean size queries, each within a set of parentheses. A size query includes a size descriptor, a value, and — depending on the descriptor — a comparison operator. The queries always measure the [content box](../values/box-edge#content-box) as the comparison. The syntax for including multiple conditions is the same as for [`@media`](@media) size feature queries. ``` @container (min-width: 400px) { /* … */ } @container (orientation: landscape) and (width > 400px) { /* … */ } @container (15em <= block-size <= 30em) { /* … */ } ``` [`aspect-ratio`](#aspect-ratio) The [`aspect-ratio`](../properties/aspect-ratio) of the container calculated as the width to the height of the container expressed as a [``](../values/ratio) value. [`block-size`](#block-size) The [`block-size`](../properties/block-size) of the container expressed as a [``](../values/length) value. [`height`](#height) The height of the container expressed as a [``](../values/length) value. [`inline-size`](#inline-size) The [`inline-size`](../properties/inline-size) of the container expressed as a [``](../values/length) value. [`orientation`](#orientation) The [orientation](@media/orientation) of the container, either `landscape` or `portrait`. [`width`](#width) The width of the container expressed as a [``](../values/length) value. #### Scroll-state container descriptors Scroll-state container descriptors are specified inside the `` as an argument for the `scroll-state()` function, for example: ``` @container scroll-state(scrollable: top) { /* … */ } @container scroll-state(scrolled: block-end) { /* … */ } @container scroll-state(stuck: inline-end) { /* … */ } @container scroll-state(snapped: both) { /* … */ } ``` Supported keywords for scroll-state container descriptors include [physical](https://developer.mozilla.org/en-US/docs/Glossary/physical_properties) and [flow relative](https://developer.mozilla.org/en-US/docs/Glossary/flow_relative_values) values. [`scrollable`](#scrollable) Queries whether the container can be scrolled in the given direction via user-initiated scrolling, such as by dragging the scrollbar or using a trackpad gesture. In other words, is there overflowing content in the given direction that can be scrolled to? Valid `scrollable` values include the following keywords: [`none`](#none) The container is not a [scroll container](https://developer.mozilla.org/en-US/docs/Glossary/scroll_container) or otherwise cannot be scrolled in any direction. [`top`](#top) The container can be scrolled towards its top edge. [`right`](#right) The container can be scrolled towards its right-hand edge. [`bottom`](#bottom) The container can be scrolled towards its bottom edge. [`left`](#left) The container can be scrolled towards its left-hand edge. [`x`](#x) The container can be scrolled horizontally towards either or both of its left-hand or right-hand edges. [`y`](#y) The container can be scrolled vertically towards either or both of its top or bottom edges. [`block-start`](#block-start) The container can be scrolled towards its block-start edge. [`block-end`](#block-end) The container can be scrolled towards its block-end edge. [`inline-start`](#inline-start) The container can be scrolled towards its inline-start edge. [`inline-end`](#inline-end) The container can be scrolled towards its inline-end edge. [`block`](#block) The container can be scrolled in its block direction towards either or both of its block-start or block-end edges. [`inline`](#inline) The container can be scrolled in its inline direction towards either or both of its inline-start and inline-end edges. If the test passes, the rules inside the `@container` block are applied to descendants of the scroll container. To evaluate whether a container is scrollable, without being concerned about the direction, use the `none` value with the `not` operator: ``` @container not scroll-state(scrollable: none) { /* … */ } ``` [`scrolled`](#scrolled) Queries whether the container was most recently scrolled in a specified direction. Valid `scrolled` values include the following keywords: [`none`](#none_2) The container is not a [scroll container](https://developer.mozilla.org/en-US/docs/Glossary/scroll_container) or otherwise has not previously been scrolled in any direction. [`top`](#top_2) The container was most recently scrolled towards its top edge. [`right`](#right_2) The container was most recently scrolled towards its right-hand edge. [`bottom`](#bottom_2) The container was most recently scrolled towards its bottom edge. [`left`](#left_2) The container was most recently scrolled towards its left-hand edge. [`x`](#x_2) The container was most recently scrolled towards either its left-hand or right-hand edges. [`y`](#y_2) The container was most recently scrolled towards either its top or bottom edges. [`block-start`](#block-start_2) The container was most recently scrolled towards its block-start edge. [`block-end`](#block-end_2) The container was most recently scrolled towards its block-end edge. [`inline-start`](#inline-start_2) The container was most recently scrolled towards its inline-start edge. [`inline-end`](#inline-end_2) The container was most recently scrolled towards its inline-end edge. [`block`](#block_2) The container was most recently scrolled towards either its block-start or block-end edges. [`inline`](#inline_2) The container was most recently scrolled towards either its inline-start or inline-end edges. If the test returns true, the rules nested in the `@container` block are applied to the descendants of the scroll container. To evaluate whether a container has recently been scrolled, without being concerned about the direction, use the `none` value with the `not` operator: ``` @container not scroll-state(scrolled: none) { /* … */ } ``` [`snapped`](#snapped) Queries whether the container is going to be snapped to a [scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll_snap) container ancestor along the given axis. Valid `snapped` values include the following keywords: [`none`](#none_3) The container is not a scroll [snap target](https://developer.mozilla.org/en-US/docs/Glossary/Scroll_snap#snap_target) for its ancestor scroll container. When implementing a `snapped: none` query, containers that *are* snap targets for the scroll container will *not* have the `@container` styles applied, whereas non-snap targets *will* have the styles applied. [`x`](#x_3) The container is a horizontal scroll snap target for its ancestor scroll container, that is, it is snapping horizontally to its ancestor. [`y`](#y_3) The container is a vertical scroll snap target for its ancestor scroll container, that is, it is snapping vertically to its ancestor. [`block`](#block_3) The container is a block-axis scroll snap target for its ancestor scroll container, that is, it is snapping to its ancestor in the block direction. [`inline`](#inline_3) The container is an inline-axis scroll snap target for its ancestor scroll container, that is, it is snapping to its ancestor in the inline direction. [`both`](#both) The container is both a horizontal and vertical scroll snap target for its ancestor scroll container and is snapping to its ancestor in both directions. The container won't match if it is only snapping to its ancestor along the horizontal *or* vertical axis. It needs to be both. To evaluate a container with a non-`none` `snapped` scroll-state query, it must be a container with a scroll container ancestor having a [`scroll-snap-type`](../properties/scroll-snap-type) value other than `none`. A `snapped: none` query will match even when there is no scroll container ancestor. Evaluations occur when [`scrollsnapchanging`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollsnapchanging_event) events fire on the scroll snap container. If the test passes, the rules inside the `@container` block are applied to descendants of the container. To evaluate whether a container is a snap target, without being concerned about the direction, use the `none` value with the `not` operator: ``` @container not scroll-state(snapped: none) { /* … */ } ``` [`stuck`](#stuck) Queries whether a container with a [`position`](../properties/position) value of [`sticky`](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning#sticky_positioning) is stuck to an edge of its scrolling container ancestor. Valid `stuck` values include the following keywords: [`none`](#none_4) The container is not stuck to any edges of its container. Note that `none` queries will match even if the container does not have `position: sticky` set on it. [`top`](#top_3) The container is stuck to the top edge of its container. [`right`](#right_3) The container is stuck to the right-hand edge of its container. [`bottom`](#bottom_3) The container is stuck to the bottom edge of its container. [`left`](#left_3) The container is stuck to the left-hand edge of its container. [`block-start`](#block-start_3) The container is stuck to the block-start edge of its container. [`block-end`](#block-end_3) The container is stuck to the block-end edge of its container. [`inline-start`](#inline-start_3) The container is stuck to the inline-start edge of its container. [`inline-end`](#inline-end_3) The container is stuck to the inline-end edge of its container. To evaluate a container with a non-`none` `stuck` scroll-state query, it must have `position: sticky` set on it, and be inside a scroll container. If the test passes, the rules inside the `@container` block are applied to descendants of the `position: sticky` container. It is possible for two values from adjacent axes to match at the same time: ``` @container scroll-state((stuck: top) and (stuck: left)) { /* … */ } ``` However, two values from opposite edges will never match at the same time: ``` @container scroll-state((stuck: left) and (stuck: right)) { /* … */ } ``` To evaluate whether a container is stuck, without being concerned about the direction, use the `none` value with the `not` operator: ``` @container not scroll-state(stuck: none) { /* … */ } ``` #### Anchored container descriptors Anchored container descriptors are specified inside the `` as an argument for the `anchored()` function, for example: ``` @container anchored(fallback: top) { /* … */ } @container anchored(fallback: flip-block flip-inline) { /* … */ } @container anchored(fallback: --custom-fallback) { /* … */ } ``` [`fallback`](#fallback) Queries whether a specific position-try fallback is currently active on an anchor-positioned container, as specified via the [`position-try-fallbacks`](../properties/position-try-fallbacks) property. Valid `fallback` values include any component value that is valid for inclusion in a `position-try-fallbacks` property value. If the `fallback` value named in the test is currently active on the anchor-positioned container, the test passes, and the rules inside the `@container` block are applied to descendants of the anchor-positioned container. ## Formal syntax ## Examples ### Setting styles based on a container's size Consider the following example of a card component with a title and some text: ``` Card title Card content ``` A container context can be created using the `container-type` property, in this case using the `inline-size` value on the `.post` class. You can then use the `@container` at-rule to apply styles to the element with the `.card` class in a container that's narrower than `650px`. ``` const post = document.querySelector(".post"); const span = document.createElement("span"); span.textContent = `.post width: ${post.clientWidth}px`; post.parentNode.insertBefore(span, post.nextSibling); // update on resize window.addEventListener("resize", () => { span.textContent = `.post width: ${post.clientWidth}px`; }); ``` ``` span { display: block; text-align: center; } .card { margin: 10px; border: 2px dotted; font-size: 1.5em; } .post { border: 2px solid; } ``` ``` /* A container context based on inline size */ .post { container-type: inline-size; } /* Apply styles if the container is narrower than 650px */ @container (width < 650px) { .card { width: 50%; background-color: lightgray; font-size: 1em; } } ``` ### Creating named container contexts Given the following HTML example which is a card component with a title and some text: ``` Card title Card content ``` First, create a container context using the `container-type` and `container-name` properties. The shorthand syntax for this declaration is described in the [`container`](../properties/container) page. ``` .post { container-type: inline-size; container-name: summary; } ``` Next, target that container by adding the name to the container query: ``` @container summary (width >= 400px) { .card { font-size: 1.5em; } } ``` ### Nested container queries It's not possible to target multiple containers in a single container query. It is possible to nest container queries which has the same effect. The following query evaluates to true and applies the declared style if the container named `summary` is wider than `400px` and has an ancestor container wider than `800px`: ``` @container summary (width > 400px) { @container (width > 800px) { /* */ } } ``` ### Container style queries Container queries can also evaluate the computed style of the container element. A *container style query* is a `@container` query that uses one or more `style()` functional notations. The boolean syntax and logic combining style features into a style query is the same as for [CSS feature queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules/Using_feature_queries). ``` @container style(), not style(), style() and style(), style() or style() { /* */ } ``` The parameter of each `style()` is a single ``. A **``** can be a valid CSS [declaration](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/Introduction#css_declarations) (the **plain** form), a CSS property or [``](../values/var#values) on its own (the **boolean** form), or a [range comparison](#range_syntax) (the **range** form). ``` @container style(--themeBackground), not style(background-color: red), style(color: green) and style(background-color: transparent), style(--themeColor: blue) or style(--themeColor: purple) { /* */ } ``` A style feature without a value evaluates to true if the computed value is different from the initial value for the given property. If the `` passed as the `style()` function's argument is a declaration, the style query evaluates to true if the declaration's value is the same as the computed value of that property for the container being queried. Otherwise, it resolves to false. The following container query checks if the [computed value](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#computed_value) of the container element's `--accent-color` is `blue`: ``` @container style(--accent-color: blue) { /* */ } ``` **Note:** If a custom property has a value of `blue`, the equivalent hexadecimal code `#0000ff` will not match unless the property has been defined as a color with [`@property`](@property) so the browser can properly compare computed values. Style features that query a shorthand property are true if the computed values match for each of its longhand properties, and false otherwise. For example, `@container style(border: 2px solid red)` will resolve to true if all 12 longhand properties (`border-bottom-style`, etc.) that make up that shorthand are true. Note that [`!important`](../values/important) is allowed in style queries but is ignored. ``` /* !important is valid but has no effect */ @container style(--themeColor: purple !important) { /* */ } ``` The global `revert` and `revert-layer` are invalid as values in a `` and cause the container style query to be false. #### Range syntax In addition to the plain `: ` form described above, a `` can be written as a **range** comparison using `=`, `<`, `<=`, `>`, or `>=`. Range syntax enables **numeric** comparisons that the plain form can't, such as `style(--columns >= 3)` or `style(--gap = 1rem)`. It compares the resolved values of both sides numerically. To evaluate a range, the browser: - Resolves each side (custom property names are looked up as if used with [`var()`](../values/var)). - Parses each side as a [``](../values/number), ` `, [``](../values/length), [``](../values/angle), [``](../values/time), [``](../values/frequency), or [``](../values/resolution). If either side can't be parsed as one of those types, or the two sides don't have the same type, the query is false. - Computes each side (evaluating any `calc()` expressions) and performs the numeric comparison. This means range syntax can't be used to compare keyword-like values: `style(--theme = dark)` is always false because `dark` isn't a numeric type. Use the plain syntax for those, for example `style(--theme: dark)`. Either side of a range can be a custom property name, a `var()` reference, a literal value, or a `calc()` expression, in either order: ``` @container style(3 = --n) { /* … */ } @container style(var(--n) = 3) { /* … */ } @container style(calc(6/2) = var(--n)) { /* … */ } ``` A range can also take a three-value form, with both comparators pointing the same way, to test whether a value falls within an interval: ``` @container style(0 < --n < 10) { /* true when --n is greater than 0 and less than 10 */ } @container style(100px > --width > 50px) { /* true when --width is less than 100px and greater than 50px */ } ``` In other words, `style(0 < --n < 10)` is equivalent to `style(0 < --n) and style(--n < 10)`. The middle value is tested against both bounds, rather than being chained left-to-right. **Note:** Plain and range syntax behave differently even when they look similar. Given `--n: calc(6/2)`, the query `style(--n: 3)` is **false** because the plain form compares the property's computed value (`calc(6/2)`) directly against `3`. The equivalent range query `style(--n = 3)` is **true** because the range form computes both sides numerically before comparing. See [Plain versus range syntax in style queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries#plain_versus_range_syntax_in_style_queries) in the container style queries guide for more details. ### Scroll-state queries See [Using container scroll-state queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries) for scroll-state query examples. ### Anchored queries See [Using anchored container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries) for anchored query examples. ## Specifications | Specification | | --- | | CSS Conditional Rules Module Level 5 # container-type | | CSS Anchor Positioning Module Level 2 # container-rule-anchored | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `container` | 105 | 105 | 110 | 91 | 16 | 105 | 110 | 72 | 16 | 20.0 | 105 | 16 | | `anchor_position_queries` | 143 | 143 | No | 127 | No | 143 | No | 94 | No | 30.0 | 143 | No | | `container-query_optional` | 148 | 148 | 149 | 132 | 26.4 | 148 | 149 | 99 | 26.4 | No | 148 | 26.4 | | `scroll-state_queries` | 133 | 133 | No | 118 | No | 133 | No | 88 | No | 29.0 | 133 | No | | `style_queries_for_custom_properties` | 111 | 111 | 151 | 97 | 18The document element cannot be a container. See [bug 271040](https://webkit.org/b/271040). | 111 | 151 | 75 | 18The document element cannot be a container. See [bug 271040](https://webkit.org/b/271040). | 22.0 | 111 | 18The document element cannot be a container. See [bug 271040](https://webkit.org/b/271040). | ## See also - [Using container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries) - [Using container size and style queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries) - [Using container scroll-state queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries) - [Using anchored container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries) - [`container-name`](../properties/container-name) - [`container-type`](../properties/container-type) - [`contain`](../properties/contain) - [`content-visibility`](../properties/content-visibility) - [`CSSContainerRule`](https://developer.mozilla.org/en-US/docs/Web/API/CSSContainerRule) API - [CSS containment module](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment) - [CSS at-rule functions](at-rule_functions) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container) --- ## Section: at-rules/@counter-style # `@counter-style` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`@counter-style`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) lets you extend predefined list styles and define your own counter styles that are not part of the predefined set of styles. The `@counter-style` rule contains [descriptors](#descriptors) defining how the counter value is converted into a string representation. While CSS provides many useful predefined counter styles, the `@counter-style` at-rule offers an open-ended method for creating counters. This at-rule caters to the needs of worldwide typography by allowing authors to define their own counter styles when the predefined styles don't fit their requirements. ## Syntax ``` @counter-style thumbs { system: cyclic; symbols: "\1F44D"; suffix: " "; } ``` The `@counter-style` at-rule is identified by a [counter style name](#counter_style_name), and the style of the named counter can be fine-tuned using a `` consisting of one or more [descriptors](#descriptors) and their values. ### Counter style name [``](#<counter-style-name>) Provides a name for your counter style. It is specified as a case-sensitive [``](../values/custom-ident) without quotes. The value should not be equal to `none`. Like all custom identifiers, the value of your counter style can't be a [CSS-wide keyword](../values/data_types#css-wide_keywords). Avoid other enumerated CSS property values, including values of [list](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists#properties) and [counter style](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles#properties) properties. The name of your counter can't be the case-insensitive [`list-style-type`](../properties/list-style-type) property values of `decimal`, `disc`, `square`, `circle`, `disclosure-open`, and `disclosure-closed`. **Note:** The non-overridable counter style names `decimal`, `disc`, `square`, `circle`, `disclosure-open`, and `disclosure-closed` cannot be used as the name of a custom counter. However, they are valid in other contexts where the `` data type is expected, such as in `system: extends `. ### Descriptors [`system`](@counter-style/system) Specifies the algorithm to be used for converting the integer value of a counter to a string representation. If the value is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`, the `symbols` descriptor must also be specified. If the value is `additive`, the `additive-symbols` descriptor must also be specified. [`symbols`](@counter-style/symbols) Specifies the symbols that are to be used for the marker representations. Symbols can contain strings, images, or custom identifiers. This descriptor is required if the `system` descriptor is set to `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`. [`additive-symbols`](@counter-style/additive-symbols) Defines the *additive tuples* for additive systems. While the symbols specified in the `symbols` descriptor are used for constructing marker representation by most algorithms, additive counter systems, such as Roman numerals, consist of a series of weighted symbols. The descriptors is a list of counter symbol along with their non-negative integer weights, listed by weight in descending order. This descriptor is required if the `system` descriptor is set to `additive`. [`negative`](@counter-style/negative) Specifies to symbols to be appended or prepended to the counter representation if the value is negative. [`prefix`](@counter-style/prefix) Specifies a symbol that should be prepended to the marker representation. Prefixes are added to the representation in the final stage, before any characters added to negative counter values by the `negative` descriptor. [`suffix`](@counter-style/suffix) Specifies, similar to the prefix descriptor, a symbol that is appended to the marker representation. Suffixes come after the marker representation, including after any characters added to negative counter values by the `negative` descriptor. [`range`](@counter-style/range) Defines the range of values over which the counter style is applicable. If a counter style is used to represent a counter value outside of the ranges defined by this descriptor, the counter style will drop back to its `fallback` style. [`pad`](@counter-style/pad) Is used when you need the marker representations to be of a minimum length. For example if you want the counters to start at 01 and go through 02, 03, 04, etc., then the `pad` descriptor is to be used. For representations larger than the specified `pad` value, the marker is constructed as normal. [`speak-as`](@counter-style/speak-as) Describes how speech synthesizers, such as screen readers, should announce the counter style. For example, the value of the list item marker can be read out as numbers or alphabets for ordered lists or as audio cues for unordered lists, based on the value of this descriptor. [`fallback`](@counter-style/fallback) Specifies the counter name of the system to fall back to if either the specified system is unable to construct the representation of a counter value or if the counter value is outside the specified `range`. If the fallback counter also fails to represent the value, then that counter's fallback is used, if one is specified. If there are either no fallback counters described or if the chain of fallback systems are unable to represent a counter value, then it will ultimately fall back to the `decimal` style. ## Formal syntax ## Examples ### Specifying symbols with counter-style ``` @counter-style circled-alpha { system: fixed; symbols: Ⓐ Ⓑ Ⓒ Ⓓ Ⓔ Ⓕ Ⓖ Ⓗ Ⓘ Ⓙ Ⓚ Ⓛ Ⓜ Ⓝ Ⓞ Ⓟ Ⓠ Ⓡ Ⓢ Ⓣ Ⓤ Ⓥ Ⓦ Ⓧ Ⓨ Ⓩ; suffix: " "; } ``` The above counter style rule can be applied to lists like this: ``` .items { list-style: circled-alpha; } ``` The above code produces the following result: ``` - one - two - three - four - five ... - twenty-five - twenty-six - twenty-seven - twenty-eight ``` See more examples on the [demo page](https://mdn.github.io/css-examples/counter-style-demo/) ([code](https://github.com/mdn/css-examples/tree/main/counter-style-demo)). ### Ready-made counter styles Find a collection of over 100 `counter-style` code snippets in the [Ready-made Counter Styles](https://w3c.github.io/predefined-counter-styles/) document. This document provides counters that meet the needs of languages and cultures around the world. The [Counter styles converter](https://r12a.github.io/app-counters/) pulls from this list to test and create copy and paste code for counter styles. ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # the-counter-style-rule | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `counter-style` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `additive-symbols` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `fallback` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `negative` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `pad` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `prefix` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `range` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `speak-as` | 91 | 91 | 33 | 77 | No | 91 | 33 | 64 | No | 16.0 | 91 | No | | `suffix` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | | `symbols` | 91Does not support `` as a value for the `symbols` descriptor. | 91Does not support `` as a value for the `symbols` descriptor. | 33Does not support `` as a value for the `symbols` descriptor. | 77Does not support `` as a value for the `symbols` descriptor. | 17 | 91Does not support `` as a value for the `symbols` descriptor. | 33Does not support `` as a value for the `symbols` descriptor. | 64Does not support `` as a value for the `symbols` descriptor. | 17 | 16.0Does not support `` as a value for the `symbols` descriptor. | 91Does not support `` as a value for the `symbols` descriptor. | 17 | | `system` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - [`counter()`](../values/counter) - [`counters()`](../values/counters) - [`symbols()`](../values/symbols) - [`list-style`](../properties/list-style), [`list-style-image`](../properties/list-style-image), [`list-style-position`](../properties/list-style-position), [`list-style-type`](../properties/list-style-type) - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style) --- ## Section: at-rules/@counter-style/additive-symbols # `additive-symbols` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`additive-symbols`** descriptor of the [`@counter-style`](../@counter-style) at-rule is used to specify counter symbols when the `@counter-style` [`system`](system) descriptor value is set as `additive`. The additive system is used to construct [sign-value numbering](https://en.wikipedia.org/wiki/Sign-value_notation) systems such as Roman numerals. ## Syntax ``` /* Single tuple */ additive-symbols: 3 "*"; /* Comma-separated list of tuples */ additive-symbols: 3 "0", 2 "\2E\20", 1 url("symbol.png"); /* Binary counter */ additive-symbols: 2 "1", 1 "0"; /* Etruscan (a civilization in ancient Italy) counter */ additive-symbols: 100 "𐌟", 50 "𐌣", 10 "𐌢", 5 "𐌡", 1 "𐌠"; ``` ### Values The descriptor accepts a comma-separated list of *additive tuples* with each tuple consisting of the following two values separated by a space: [``](../../values/integer) A non-negative integer values specifying the integer weight of the associated symbol value of the tuple. [``](symbols#symbol) Specifies the counter symbol to be used for the weight value defined by the associated `` weight value of the tuple. **Note:** The additive tuples must be specified in order of descending weight; otherwise, the descriptor declaration isn't valid and is ignored. ## Description The `additive-symbols` descriptor defines a comma-separated list of *additive tuples*. Each *additive tuple* contains a space-separated non-negative integer and counter symbol. To be valid, the list must be in the descending order of integer. The integer and symbol are concatenated together to form the counter symbol. When the `system` descriptor value is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`, use the [`symbols()`](../../values/symbols) descriptor instead of `additive-symbols`. ## Formal definition ## Formal syntax ## Examples ### Specifying additive symbols #### HTML In this example, [`system: additive`](system) along with the `additive-symbols` descriptor values specify how numbers should be represented as Roman numerals. The value of each [`- `](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) element in the list is converted to a Roman numeral according to the rules defined in [`@counter-style`](../@counter-style). ``` One - Two - Three - Four - Five - 109 - 110 ``` #### CSS ``` @counter-style uppercase-roman { system: additive; additive-symbols: 1000 M, 900 CM, 500 D, 400 CD, 100 C, 90 XC, 50 L, 40 XL, 10 X, 9 IX, 5 V, 4 IV, 1 I; } ul { list-style: uppercase-roman; padding-left: 5em; } ``` #### Result For the list item with the value of `109`, the numeral `C` represents `100`, and `IX` represents `9`. This generates `CIX` counter for the list item `109`. The next list item automatically gets a value of `110`. The roman numeral `CX` is derived from `C` for `100` and `X` for `10`. ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-symbols | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `additive-symbols` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), [`fallback`](fallback) - List style properties: [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols) function to create anonymous counter styles - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/additive-symbols](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/additive-symbols) --- ## Section: at-rules/@counter-style/fallback # `fallback` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`fallback`** descriptor of the [`@counter-style`](../@counter-style) at-rule can be used to specify a counter style to fall back to if the counter style being defined cannot create a marker representation for a particular counter value. ## Syntax ``` /* Keyword values */ fallback: lower-alpha; fallback: custom-gangnam-style; ``` ## Value The descriptor takes a single `` as its value: [``](../@counter-style#counter-style-name) Provides the name of the counter style to be used as the fallback, which is either the case-sensitive `` of a custom CSS counter style (without quotes) or a case-insensitive [`list-style-type`](../../properties/list-style-type) property value such as `decimal`, `disc`, and so on. If omitted, the counter fallback defaults to `decimal`. ## Description The counter style provided as the value of the `fallback` descriptor is used when a [`range`](range) descriptor is specified for a counter style; the `fallback` style is used to represent all the values that fall outside the range. The `fallback` style is also used when the `fixed` [`system`](system) is used and there are not enough symbols to cover all the list items; the `fallback` style is used to represent all the values beyond the scope of the fixed system. In both these cases, and any other time the defined counter cannot create a specific counter value, the `fallback` style is used. If the specified fallback style is also unable to construct a representation, then the `fallback` value of that fallback counter is used. If that fallback style's fallback is also unable to construct a representation, then that fallback's fallback is used. This falling back continues until a fallback is found that can construct the counter-representation. If no fallback `fallback` value is able to construct a representation―if a fallback style doesn't have a `fallback` value set, or if a `fallback` value is not specified or invalid―the `fallback` defaults to `decimal`. ## Formal definition ## Formal syntax ## Examples ### Specifying a fallback counter style #### HTML ``` - One - Two - Three - Four - Five ``` #### CSS ``` @counter-style fallback-example { system: fixed; symbols: "\24B6" "\24B7" "\24B8"; fallback: upper-alpha; } .list { list-style: fallback-example; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-fallback | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `fallback` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - Other [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), and [`speak-as`](speak-as) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols): the functional notation for creating anonymous counter styles © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/fallback](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/fallback) --- ## Section: at-rules/@counter-style/negative # `negative` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`negative`** descriptor of the [`@counter-style`](../@counter-style) at-rule lets you define how negative counter values are represented when defining custom counter styles. The value of the `negative` descriptor defines the symbols to be added before and after the counter representation when the counter's value is negative. ## Syntax ``` /* One value */ negative: "--"; /* Adds '--' before if counter value is negative */ /* Two values */ negative: "(" ")"; /* Adds '(- before and ')' after if counter value is negative */ ``` ### Values The `negative` descriptor accepts up to two [``](symbols#values) values. [``](#<symbol>) If only one value is specified, it is added before the counter representation when the counter is negative. If two values are specified, the first one is added before and the second one is added after the counter representation when the counter is negative. ## Description If the counter value is negative, the specified `` for the `negative` descriptor is added before the counter representation, replacing the default `-` for negative values. The second ``, if specified, is added after the counter representation. The `negative` descriptor is relevant in two cases: if counter styles have the `system` value of `symbolic`, `alphabetic`, `numeric`, and `additive` and the count is negative; and if `system` value is `extends` and the extended counter style itself uses a negative sign. For systems that don't support negative counter values, specifying the `negative` descriptor has no effect and is ignored. ## Formal definition ## Formal syntax ## Examples ### Rendering negative counters This example [extends](system#extends) the [`decimal`](../../properties/list-style-type#decimal) list style. The `negative` descriptor is used to add `(-` and `)` before and after negative counter values. #### HTML ``` - Negative three - Negative two - Negative one - Zero - One ``` #### CSS ``` @counter-style neg { system: extends decimal; negative: "(-" ")"; suffix: ": "; } ol { list-style: neg; } ``` #### Result The prefix and suffix listed as the value of the `negative` descriptor are only added to the marker when the counter value is less than zero. ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-system | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `negative` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), [`fallback`](fallback) - List style properties: [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols) function to create anonymous counter styles - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/negative](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/negative) --- ## Section: at-rules/@counter-style/pad # `pad` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`pad`** descriptor of the [`@counter-style`](../@counter-style) at-rule is used to set a minimum length for marker representations. ## Syntax ``` pad: 3 "0"; pad: "+" 5; ``` ### Values The descriptor accepts the following two values, which are separated by a space and can be specified in any order: [``](../../values/integer) Specifies the minimum length that all marker representations must reach. The value must be non-negative. In the case of the `pad` descriptor, this value is also known as the *pad length*. [``](symbols#symbol) Specifies the symbol to be used for padding if the minimum length defined by the `` is not reached. In the case of the `pad` descriptor, this value is also known as the *padding symbol*. ## Description Use the `pad` descriptor when you need the marker representations to be of a minimum length. If a marker representation is shorter than the specified pad length, then the marker representation will be padded with the specified padding symbol. Marker representations longer than the pad length are displayed without any additional padding. The `pad` descriptor takes an `` for the minimum marker length and a `` for the padding. A common use case of the `pad` descriptor is when you need a list to start numbering from `01` and go through `02`, `03`, `04`, and so on, instead of just `1`, `2`, `3`, and `4`. By specifying the `pad` descriptor as `pad: 2 "0"` in this case, the browser ensures to make the counter at least two characters long and adds a padding with `0` to reach the minimum two-character length where needed. Counters that are already two or more characters long in this example will be displayed normally, without padding. ## Formal definition ## Formal syntax ## Examples ### Padding a counter This example extends the `decimal` [`system`](system) to create a counter that is at least three characters long, padding shorter counters with `0` to reach that minimum length. A [`suffix`](suffix) descriptor has been added to make the output more legible. #### HTML ``` - One - Two - Three - Forty - Forty-one - Two hundred - Three thousand - and so on ``` #### CSS ``` @counter-style pad-example { system: extends decimal; suffix: ": "; pad: 3 "0"; } ul { list-style: pad-example; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-pad | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `pad` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`speak-as`](speak-as), [`fallback`](fallback) - List style properties: [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols) function to create anonymous counter styles - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/pad](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/pad) --- ## Section: at-rules/@counter-style/prefix # `prefix` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The [`@counter-style`](../@counter-style) rule's **`prefix`** descriptor specifies content that will be added to the beginning of the counter's marker representation. When the counter value is negative, the `prefix` comes before the negative sign and any other ``s added by the [`negative`](negative) descriptor. ## Syntax ``` /* value: string, image, or identifier */ prefix: "»"; prefix: "Page "; prefix: url("bullet.png"); ``` ### Values The **`prefix`** descriptor takes as its value a single ``: [``](#<symbol>) Specifies a `` — a [``](../../values/string), [``](../../values/image), or [``](../../values/custom-ident) — that is prepended to the marker representation. ## Formal definition ## Formal syntax ## Examples ### Adding a prefix to a counter In this example, each counter number is prefixed by "Book " (with a space) and followed by a colon (`:`). The colon is added with the [`suffix`](suffix) descriptor. #### HTML ``` - Flamer, by Mike Curato - Gender Queer: A Memoir, by Maia Kobabe - Tricks, by Ellen Hopkins - The Handmaid's Tale: The Graphic Novel, by Margaret Atwood - Crank, by Ellen Hopkins ``` #### CSS ``` @counter-style books { system: numeric; symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9"; prefix: "Book "; suffix: ": "; } .books { list-style: books; padding-left: 15ch; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-prefix | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `prefix` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - Other [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`suffix`](suffix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), and [`fallback`](fallback) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols): the functional notation for creating anonymous counter styles - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/prefix](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/prefix) --- ## Section: at-rules/@counter-style/range # `range` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`range`** descriptor lets the author specify one or more ranges of counter values for which the style is applied when defining custom counter styles with the [`@counter-style`](../@counter-style) at-rule. When the `range` descriptor is included, the defined counter will only be used for values in the set ranges. If the counter value is outside the specified range, the fallback style will be used to construct the representation of that marker. ## Syntax ``` /* Keyword value */ range: auto; /* Range values */ range: 2 5; range: infinite 10; range: 6 infinite; range: infinite infinite; /* Multiple range values */ range: 2 5, 8 10; range: infinite 6, 10 infinite; ``` ### Values The value is a comma-separated list of ranges each including a lower and upper limit or the keyword `auto`. [`auto`](#auto) The entire set of numbers representable by the counter [`system`](system). Those range values depends on the counter system: - For `cyclic`, `numeric`, and `fixed` systems, the range is negative `infinity` to positive `infinity`. - For `alphabetic` and `symbolic` systems, the range is `1` to positive `infinity`. - For `additive` systems, the range is `0` to `positive` infinity. - When using `extend` to extend a system, the range is whatever `auto` would produce for the system being extended, including extensions of complex predefined styles, such as some Japanese, Korean, Chinese, and Ethiopian counter styles. [`[ [ | infinite ]{2} ]#`](#<integer>_infinite_2) Each range within the comma separated list of ranges includes two values, each being either an [``](../../values/integer) or the keyword `infinite`. If `infinite` is used as the first value in a range, it represents negative infinity; if it is used as the second value, it represents positive infinity. The first value of each range is the lower bound for the range and the second value is the upper bound, inclusive. If the lower bound of any range in the list is higher than the upper bound, the entire `range` descriptor is invalid and will be ignored. ## Description The value of the `range` descriptor can be either `auto` or a comma separated list of lower and upper bound ranges specified using negative or positive integers or the keyword `infinite`. ### Understanding `auto` When the value is set to `auto`, the range is the default range for the counter system. If the `system` is `cyclic`, `numeric`, or `fixed`, the range will be from negative infinity to positive infinity. If the `system` is `alphabetic` or `symbolic`, the range will be from `1` to positive `infinity`. For `system: additive`, `auto` results in the range `0` to positive `infinity`. When extending a counter, if `range` is set to `auto`, the range value will be the range of the `system` of the counter that is being extended, not the `range` value, if any, of that counter. For example, if counter "B" has the `system: extends A` set, with counter being an `alphabetic` counter, setting `range: auto` on "B" sets the range of "B" from `1` to `infinity`. This is the range of the `alphabetic` system, not necessarily the range set in the "A" counter style definition. With `range: auto` set on "B", the `range` is set to the default range of the `alphabetic` system, not the `range` value set in counter A's descriptor list. ### `infinite` explained When range is specified as integers (versus `auto`), the value `infinite` can be used to denote infinity. If *infinite* is specified as the first value in a range, then it is interpreted as negative infinity. If used as the upper bound, the second value in the range pair, it is taken as positive infinity. ### List of ranges The value of `range` is either `auto`, discussed above, or a comma separated list of one or more ranges. The range of the counter style is the union of all the ranges defined in the list. Each range in the list of ranges takes two values. Those values are either an [``](../../values/integer) or the keyword `infinite`. The first value is the *lower bound*, inclusive. The second value is the *upper bound*, inclusive. For two integer values, the lower value must come first. If the lower bound of any range in the list is higher than the upper bound, the entire `range` descriptor is invalid and will be ignored. The `infinite` keyword will not invalidate the range, because the position of `infinite` determines its value; either negative or positive infinity based on whether it's the lower bound or upper bound, respectively. ## Formal definition ## Formal syntax ## Examples ### Setting counter style over a range #### HTML ``` - One - Two - Three - Four - Five - Six - Seven - Eight - Nine - Ten ``` #### CSS ``` @counter-style range-multi-example { system: cyclic; symbols: "\25A0" "\25A1"; range: 2 4, 7 9; } .list { list-style: range-multi-example; } ``` #### Result The first range is the list of ranges includes 2, 3, and 4. The second includes 7, 8, and 9. The range is the union of these two ranges, or 2, 3, 4, 7, 8, and 9. ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-range | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `range` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - Other [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`pad`](pad), [`speak-as`](speak-as), and [`fallback`](fallback) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols): the functional notation for creating anonymous counter styles. - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/range](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/range) --- ## Section: at-rules/@counter-style/speak-as # `speak-as` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`speak-as`** descriptor specifies how a counter symbol constructed with a given [`@counter-style`](../@counter-style) will be represented in the spoken form. For example, an author can specify a counter symbol to be either spoken as its numerical value or just represented with an audio cue. ## Syntax ``` /* Keyword values */ speak-as: auto; speak-as: bullets; speak-as: numbers; speak-as: words; speak-as: spell-out; /* @counter-style name value */ speak-as: ; ``` ### Values [`auto`](#auto) If the value of `speak-as` is specified as `auto`, then the effective value of `speak-as` will be determined based on the value of the [`system`](system) descriptor: - If the value of `system` is `alphabetic`, the effective value of `speak-as` will be `spell-out`. - If `system` is `cyclic`, the effective value of `speak-as` will be `bullets`. - If `system` is `extends`, the value of `speak-as` will be the same as if `speak-as: auto` is specified on the extended style. - For all other cases, specifying `auto` has the same effect as specifying `speak-as: numbers`. [`bullets`](#bullets) A phrase or an audio cue defined by the [user agent](https://developer.mozilla.org/en-US/docs/Glossary/user_agent) for representing an unordered list item will be read out. [`numbers`](#numbers) The numerical value of the counter will be read out in the document language. [`words`](#words) The user agent will generate a counter value as normal and read it out as a word in the document language. [`spell-out`](#spell-out) The user agent will generate a counter representation as normal and would read it out letter by letter. If the user agent doesn't know how to read out a particular counter symbol, the user agent might read it out as if the value of `speak-as` was `numbers`. [``](#<counter-style-name>) The name of another counter style, specified as a [``](../../values/custom-ident). If included, the counter will be spoken out in the form specified in that counter style, kind of like specifying the [`fallback`](fallback) descriptor. If the specified style does not exist, `speak-as` defaults to `auto`. ## Accessibility Assistive technology support is very limited for the `speak-as` property. Do not rely on it to convey information critical to understanding the page's purpose. | [Let's Talk About Speech CSS | CSS Tricks](https://css-tricks.com/lets-talk-speech-css/) (2017) | | --- | --- | ## Formal definition ## Formal syntax ## Examples ### Setting the spoken form for a counter In this example, the counter system is fixed with unintelligible symbols used for the visual markers. However, the `speak-as` descriptor is used to set the list item markers as numbers in the accessibility tree. When supported, numbers rather than visual markers will be read out by screen readers. To experience the result of the `speak-as` descriptor, use assistive technology such as VoiceOver or another screen reader or view the [accessibility panel](https://firefox-source-docs.mozilla.org/devtools-user/index.html#accessibility-inspector) in the developer tools of a browser that supports `speak-as`. #### HTML ``` - I had one apple - I ate two bananas - I devoured three oranges - I am not hungry for dinner - But I'll have five scoops of ice cream for dessert ``` #### CSS ``` @counter-style speak-as-example { system: fixed; symbols:     ; suffix: " "; speak-as: numbers; } .list { list-style: speak-as-example; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-speak-as | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `speak-as` | 91 | 91 | 33 | 77 | No | 91 | 33 | 64 | No | 16.0 | 91 | No | ## See also - Other [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), and [`fallback`](fallback) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols): the functional notation for creating anonymous counter styles. - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/speak-as](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/speak-as) --- ## Section: at-rules/@counter-style/suffix # `suffix` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`suffix`** descriptor of the [`@counter-style`](../@counter-style) rule specifies content that will be added to the end of the marker representation. ## Syntax ``` /* value: string, image, or identifier */ suffix: ""; suffix: ") "; suffix: url("bullet.png"); ``` ### Values The **`suffix`** descriptor takes as its value a single ``: [``](#<symbol>) Specifies a `` that is appended to the marker representation. It may be a [``](../../values/string), [``](../../values/image), or [``](../../values/custom-ident). ## Formal definition ## Formal syntax ## Examples ### Setting a suffix for a counter #### HTML ``` - One - Two - Three - None of the above ``` #### CSS ``` @counter-style options { system: fixed; symbols: A B C D; suffix: ") "; } .choices { list-style: options; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-suffix | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `suffix` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - Other [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), and [`fallback`](fallback) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols): the functional notation for creating anonymous counter styles - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module - [CSS lists and counters](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Lists) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/suffix](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/suffix) --- ## Section: at-rules/@counter-style/symbols # `symbols` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`symbols`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor of the [`@counter-style`](../@counter-style) at-rule is used to specify the symbols for creating counter representations in the specified counter system. Specifying this descriptor is mandatory when the value of the [`system`](system) descriptor is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`. ## Syntax ``` symbols: A B C D E; symbols: "\24B6" "\24B7" "\24B8" D E; symbols: "0" "1" "2" "4" "5" "6" "7" "8" "9"; symbols: url("one.svg") url("two.svg") url("three.svg"); symbols: indic-numbers; ``` ### Values The `symbols` descriptor is specified as a list of one or more space-separated `` values. [``](#<symbol>) Specifies the symbol to use within the counter system. Each symbol in the list can be either a [``](../../values/string), an [``](../../values/image), or a [``](../../values/custom-ident). The `` value can, in turn, be specified as a [``](../../values/url_value) or [``](../../values/gradient). **Note:** When using an [identifier](https://developer.mozilla.org/en-US/docs/Glossary/identifier) for a symbol, note that [ASCII](https://developer.mozilla.org/en-US/docs/Glossary/ASCII) non-letters such as `*`, `"`, and `\` are not considered identifiers. They must be either quoted as a string or escaped. ## Description A symbol can be a string, image, or identifier. It is used within the [`@counter-style`](../@counter-style) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules). When the value of the [`system`](system) descriptor is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`, the `symbols` descriptor must be specified. For the `additive` system, use the [`additive-symbols`](additive-symbols) descriptor instead to specify the symbols. While a space between quoted symbols is not required, it makes CSS more readable. To use a quote as a symbol, either escape the quote character or enclose the character within different quotes, such as `"'"`. When defining symbols with identifiers instead of strings, be sure to use identifier syntax rules. For example, as noted above, ASCII non-letters such as `*` are not identifiers and must be either quoted or escaped. Hex escape characters are followed by a space. This space may look like the space separating two identifiers, but it enables digits to follow hex-escaped characters. This means that two spaces must be included after a hex-escaped identifier to separate it from the next identifier. For example, it is better to use the string `"\2A 1"` instead of `\2A 1` with two spaces, as your code tools might remove double spaces. It is generally safer to quote identifiers that need to be escaped or use strings. ## Formal definition ## Formal syntax ## Examples ### Setting counter symbols In this example, the list of values for the `symbols` descriptor include letters (`A`, `D`, `E`), a number within quotes (`"1"`), and a hex-escape identifier within quotes (`"\24B7"`) for the character `Ⓑ`. #### HTML ``` - One - Two - Three - Four - Five ``` #### CSS ``` @counter-style symbols-example { system: fixed; symbols: A "1" "\24B7" D E; } .list { list-style: symbols-example; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-symbols | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `symbols` | 91Does not support `` as a value for the `symbols` descriptor. | 91Does not support `` as a value for the `symbols` descriptor. | 33Does not support `` as a value for the `symbols` descriptor. | 77Does not support `` as a value for the `symbols` descriptor. | 17 | 91Does not support `` as a value for the `symbols` descriptor. | 33Does not support `` as a value for the `symbols` descriptor. | 64Does not support `` as a value for the `symbols` descriptor. | 17 | 16.0Does not support `` as a value for the `symbols` descriptor. | 91Does not support `` as a value for the `symbols` descriptor. | 17 | ## See also - [`@counter-style`](../@counter-style) descriptors: [`system`](system), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), [`fallback`](fallback) - List style properties: [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols) function - [``](../../values/url_value) type - [CSS counter styles](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Counter_styles) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/symbols](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/symbols) --- ## Section: at-rules/@counter-style/system # `system` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2023. The **`system`** descriptor specifies the algorithm to be used for converting the integer value of a counter to a string representation. It is used in a [`@counter-style`](../@counter-style) to define the behavior of the defined style. If the algorithm specified in the `system` descriptor is unable to construct the representation for a particular counter value, then that value's representation will be constructed using the fallback system provided. ## Syntax ``` /* Keyword values */ system: cyclic; system: numeric; system: alphabetic; system: symbolic; system: additive; system: fixed; /* Other values */ system: fixed 3; system: extends decimal; system: extends circled-letters; ``` ## Values This may take one of three forms: - One of the keyword values `cyclic`, `numeric`, `alphabetic`, `symbolic`, `additive`, or `fixed`. - The keyword value `fixed` along with an integer. - The keyword value `extends` along with a [``](../@counter-style#counter-style-name) value. The values include: [`cyclic`](#cyclic) Cycles through the list of symbols provided in the [`symbols`](symbols) descriptor. Once the end of the list is reached, the cycle will loop back to the beginning and start over. This value is useful both for basic bullet styles with just one symbol and for styles with multiple symbols. At least one symbol must be specified in the `symbols` descriptor, otherwise the counter style is not valid. [`numeric`](#numeric) Interprets the counter symbols as digits in a [place-value numbering system](https://en.wikipedia.org/wiki/Positional_notation). The numeric system is similar to the `alphabetic` system, described above. The main difference is that in the `alphabetic` system, the first counter symbol given in the `symbols` descriptor is interpreted as `1`, the next as `2`, and so on. However, in the numeric system, the first counter symbol is interpreted as 0, the next as `1`, then `2`, and so on. At least two counter symbols must be specified in the `symbols` descriptor or the counter style is not valid. [`alphabetic`](#alphabetic) Interprets the specified symbols as digits, to an alphabetic numbering system. If the characters `"a"` to `"z"` are specified as symbols in a counter style, with the `alphabetic` system, then the first 26 counter representations will be `"a"`, `"b"` up to `"z"`. Until this point, the behavior is the same as that of the `symbolic` system, described above. However, after `"z"`, it will continue as `"aa"`, `"ab"`, `"ac"`… The `symbols` descriptor must contain at least two symbols or the counter style is not valid. The first counter symbol provided in the `symbols` descriptor is interpreted as `1`, the next as `2`, and so on. This system is also defined strictly over positive counter values. [`symbolic`](#symbolic) Cycles through the symbols provided in the `symbols` descriptor list repeatedly, doubling, tripling, and so on, the symbols on each successive pass through the list. For example, if two symbols "◽" and "◾" are specified in the `symbols` descriptor, on each successive pass, they will become "◽◽" and "◾◾", then "◽◽◽" and "◾◾◾", and so on in subsequent passes. At least one symbol must be specified in the `symbols` descriptor, otherwise the counter style is not valid. This counter system works for positive counter values only. [`additive`](#additive) Used to represent "sign-value" numbering systems, such as Roman numerals, which rather than reuse digits in different positions to obtain different values, define additional digits for larger values. The value of a number in such a system can be found out by adding the digits in the number. An additional descriptor called `additive-symbols` must be specified with at least one *additive tuple*, or else the counter style rule will not be valid. An additive tuple is similar to a composite counter symbol, which is made up of two parts: a normal counter symbol and a non-negative integer weight. The additive tuples must be specified in the descending order of their weights or the system is invalid. [`fixed`](#fixed) or `fixed ` Defines a finite set of symbols, iterating once through the list of symbols provided in the `symbols` descriptor. Once the specified symbols have been iterated through, the fallback counter style is used. This keyword value is useful in cases where the counter style values are finite. At least one symbol must be specified in the `symbols` descriptor, otherwise the counter style is not valid. The `fixed` keyword can be followed by an optional [``](../../values/integer) value. If specified, the `` value indicates the item in the list that will get the first symbol from the list of symbols. If omitted, the default value of `integer` is `1`, which gives the first item in the list the first symbol. [`extends`](#extends) Extends the algorithm of another browser- or author-defined counter style by allowing the alteration of some aspects of the extended counter style. Any unspecified descriptors and their values are inherited from the extended counter style specified. If the counter style name specified with `extends` is not yet defined, the `decimal` counter style will be extended by default. It must not contain a `symbols` or `additive-symbols` descriptor, otherwise the counter style rule will be invalid. If one or more counter styles definitions form a cycle with their `extends` values, the browser will treat all the participating counter styles as extending from the `decimal` style. **Note:** The [`symbols`](symbols) descriptor is required when the value is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`. The [`additive-symbols`](additive-symbols) descriptor is required if the `additive` value is set. ## Formal definition ## Formal syntax ## Examples ### Cyclic counter The `cyclic` value iterates through the list of symbols, repeating the list as necessary: #### CSS ``` - One - Two - Three - Four - Five - Six ``` ``` @counter-style fisheye { system: cyclic; symbols: ◉ ➀; suffix: ": "; } ul { list-style: fisheye; } ``` #### Result ### Fixed counter The `fixed` value iterates through the list of symbols only once, starting the single cycle at the list item number indicated by the `integer` value: #### CSS ``` - One - Two - Three - Four - Five - Six ``` ``` @counter-style circled-digits { system: fixed 3; symbols: ➀ ➁ ➂; suffix: ": "; } ul { list-style: circled-digits; } ``` #### Result ### Symbolic counter The `symbolic` value loops through the list defined in the `symbols` descriptor, doubling and tripling the number of symbols for the second and third cycles through the list, respectively: #### CSS ``` - One - Two - Three - Four - Five - Six - Seven - Eight ``` ``` @counter-style abc { system: symbolic; symbols: a b c; suffix: ". "; } ul { list-style: abc; } ``` #### Result ### Alphabetic counter #### CSS ``` - One - Two - Three - Four - Five - Six - Seven - Eight ``` ``` @counter-style abc { system: alphabetic; symbols: a b c; suffix: ". "; } ul { list-style: abc; } ``` #### Result ### Numeric counter The first symbol provided in the `symbols` descriptor is interpreted as `0` here. #### CSS ``` - One - Two - Three - Four - Five - Six - Seven - Eight ``` ``` @counter-style abc { system: numeric; symbols: a b c; suffix: ". "; } ul { list-style: abc; } ``` #### Result ### Numeric counter with numeric symbols As shown in the following example, if digits from `0` to `9` are specified as symbols, this counter style will render symbols same as the decimal counter style. #### CSS ``` - One - Two - Three - Four - Five - Six - Seven - Eight - Nine - Ten ``` ``` @counter-style numbers { system: numeric; symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9"; suffix: "."; } ul { list-style: numbers; } ``` #### Result ### Additive counter This example renders a list using Roman numerals. Notice that a `range` is specified. This is because the representation will produce correct Roman numerals only until the counter value of `3999`. Once outside of the range, the rest of the counter representations will be based on the `decimal` style, which is the fallback. If you need to represent counter values as Roman numerals, you could use either one of the predefined counter styles, `upper-roman` or `lower-roman`, rather than recreating the rule yourself. #### HTML We use the [`start`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/ol#start) attribute on the ` ` element to demonstrate that counting doesn't need to start at `1`. Additionally, we use the [`value`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/li#value) attribute on the fifth [`- `](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li) element to demonstrate that the counters you define using `@counter-style` behave just like native counters. ``` 48 - 49 - 50 - 51 - 109 - 110 ``` #### CSS ``` @counter-style uppercase-roman { system: additive; range: 1 3999; additive-symbols: 1000 M, 900 CM, 500 D, 400 CD, 100 C, 90 XC, 50 L, 40 XL, 10 X, 9 IX, 5 V, 4 IV, 1 I; } ol { list-style: uppercase-roman; padding-left: 5em; } ``` #### Result ### Extending a counter This example uses the algorithm, symbols, and other properties of [`lower-alpha`](../../properties/list-style-type#lower-alpha), one of the several native [`list-style-type`](../../properties/list-style-type) counter values, but extends it by removing the period (`'.'`) after the counter representation and enclosing the characters in parentheses, as in `(a)` and `(b)`. #### HTML ``` - One - Two - Three - Four - Five ``` #### CSS ``` @counter-style alpha-modified { system: extends lower-alpha; prefix: "("; suffix: ") "; } ul { list-style: alpha-modified; } ``` #### Result ## Specifications | Specification | | --- | | CSS Counter Styles Level 3 # counter-style-system | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `system` | 91 | 91 | 33 | 77 | 17 | 91 | 33 | 64 | 17 | 16.0 | 91 | 17 | ## See also - Other [`@counter-style`](../@counter-style) descriptors, including [`symbols`](symbols), [`additive-symbols`](additive-symbols), [`negative`](negative), [`prefix`](prefix), [`suffix`](suffix), [`range`](range), [`pad`](pad), [`speak-as`](speak-as), and [`fallback`](fallback) - [`list-style`](../../properties/list-style), [`list-style-image`](../../properties/list-style-image), [`list-style-position`](../../properties/list-style-position) - [`symbols()`](../../values/symbols), the functional notation for creating anonymous counter styles. © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/system](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@counter-style/system) --- ## Section: at-rules/@custom-media # `@custom-media` CSS at-rule Baseline Limited availability This feature is not Baseline because it does not work in some of the most widely-used browsers. **Experimental:** **This is an experimental technology** Check the [Browser compatibility table](#browser_compatibility) carefully before using this in production. **Experimental:** **This is an experimental technology** Check the [Browser compatibility table](#browser_compatibility) carefully before using this in production. The **`@custom-media`** CSS [at-rule](../at-rules) defines aliases for long or complex [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries). Instead of repeating the same hardcoded `` in multiple [`@media`](@media) at-rules, it can be defined once in a `@custom-media` at-rule and referenced throughout the stylesheet whenever needed. ## Syntax ``` @custom-media [ | true | false ]; @custom-media --media-query-name (width < 1200px); @custom-media --media-query-name (width < 1200px), (orientation: portrait); ``` ### Values [``](#<extension-name>) A [``](../values/dashed-ident); the name identifying the custom media query. Represented value The value aliased by the custom media query. Possible values are: [``](#<media-query-list>) A comma-separated [list of `` values](@media#description). [`true`](#true) The `@custom-media` value always evaluates to `true`. [`false`](#false) The `@custom-media` value always evaluates to `false`. ## Description When building responsive interfaces, the same media condition often needs to be repeated across multiple [`@media`](@media) at-rules, sometimes across different files and teams. Duplicating media queries increases the risk of mistakes, makes refactoring harder, and creates unnecessary maintenance overhead. Any time a media query changes, every instance must be found and updated manually — a process that can be both error-prone and difficult to track in large codebases. The `@custom-media` at-rule solves this problem by letting you define **named aliases** for media queries. Instead of repeating the full media query everywhere, you declare the media condition once as a custom media query and reference its alias throughout your stylesheets. With this in place, updating the underlying media query requires a single change in one location. Custom media queries can be composed from others by referencing their alias names inside the media query features. This enables building more expressive, layered conditions. However, a custom media query cannot refer to itself, nor can it form part of a circular chain of references. Any circular dependency — direct or indirect — invalidates all custom media queries involved in that loop. If multiple `@custom-media` rules define the same `` name, the rule that is in scope at the time a `@media` rule is evaluated is used. Earlier references are not retroactively updated when a later `@custom-media` rule is declared. ### Evaluating media queries with logical operators Custom media queries accept the full range of CSS logical operators — `not`, `and`, and `or` (comma-separated or using the `or` keyword). Because a `@custom-media` value is just a normal ``, you can combine, invert, or group conditions exactly as you would in a regular `@media` rule. #### Using the `not` operator The `not` operator negates an entire media condition. This is useful when you want a rule to apply only when a specific condition is `false`. ``` @custom-media --no-script not (scripting); @media (--no-script) { } ``` #### Using the `and` operator The `and` operator lets you combine multiple conditions that must all be `true`. ``` @custom-media --medium-screen (min-width: 40em) and (max-width: 60em); @media (--medium-screen) { } ``` This alias only matches when the viewport is within the specified width range. #### Using the `or` operator The logical `or` operator (or its comma alias, when combining media types) creates a media query that matches if any of the listed conditions are `true`. ``` @custom-media --screen-or-print screen, print; @custom-media --narrow-or-tall (width < 600px) or (height > 800px); @media (--screen-or-print) { } @media (--narrow-or-tall) { } ``` The `--screen-or-print` alias uses a comma to match either the `screen` or `print` media type. The `--narrow-or-tall` alias uses the `or` keyword to combine two media features, matching when the viewport is narrower than 600px, taller than 800px, or both. ## Formal syntax ## Examples ### Updating multiple media queries In this example, the `@custom-media` at-rule is used on a responsive website that uses a particular breakpoint in several places: ``` @custom-media --narrow-window (width < 32em); @media (--narrow-window) { } @media (--narrow-window) and (hover) { } @media (--narrow-window) and (orientation: portrait) { } ``` If the breakpoint needs to be changed, it can be updated in one place to adjust all dependent media queries across the whole site. ### Grouping multiple responsive breakpoints Here, the `@custom-media` at-rule is used to set multiple breakpoints in a single place, improving maintainability and simplifying responsive design management across multiple stylesheets: ``` /* general.css */ @custom-media --mobile-screen (width < 480px); @custom-media --tablet-screen (width < 768px); @custom-media --laptop-screen (width < 1024px); @custom-media --desktop-screen (width < 1440px); @custom-media --widescreen (width > 1441px); ``` ``` /* layout.css */ .container { padding: 1rem; } @media (--mobile-screen) { .container { padding: 0.5rem; } } @media (--laptop-screen) { .container { max-width: 1200px; } } @media (--widescreen) { .container { max-width: 1400px; padding: 2rem; } } ``` ``` /* typography.css */ @media (--tablet-screen) { .container { font-size: 0.9rem; } } @media (--laptop-screen) { .container { font-size: 1rem; } } @media (--widescreen) { .container { font-size: 1.1rem; } } ``` Grouping all the breakpoints in a single location makes it easier to maintain the responsive design. When a breakpoint needs adjustment, it only requires a single update to the associated `@custom-media` definition, ensuring consistency across all stylesheets. ### Using `true` and `false` keywords The following example shows how the `true` and `false` keywords can be used with `@custom-media` to create media queries that always or never match, respectively. ``` @custom-media --enabled true; @custom-media --disabled false; @media (--enabled) { /* These styles always apply */ body { background-color: blue; } } @media (--disabled) { /* These styles never apply */ body { background-color: red; } } ``` This can be useful for feature flags or conditional logic within stylesheets. ### Overriding existing `@custom-media` rules In this example, one `@custom-media` rule is overridden by another `@custom-media` rule using the same `` name. ``` @custom-media --mobile-breakpoint (width < 320px); @media (--mobile-breakpoint) { .container { grid-template-columns: 2fr 1fr; } } @custom-media --mobile-breakpoint (width < 480px); ``` When multiple `@custom-media` rules use the same name, the rule that is in scope at the time a `@media` rule is evaluated is used. Earlier references are not retroactively updated when a later `@custom-media` rule is declared. For example, in the code above, the `--mobile-breakpoint` reference inside the `@media` rule is evaluated as `(width < 320px)`, so the `.container` rule is only applied when the viewport is less than 320px wide, even though `--mobile-breakpoint` is redefined as `(width < 480px)` later in the stylesheet. **Note:** The overriding behavior of `@custom-media` is still under discussion in the CSS specification and may change in the future. See the [Browser compatibility](#browser_compatibility) section for current support status. ## Specifications | Specification | | --- | | Media Queries Level 5 # at-ruledef-custom-media | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `custom-media` | No | No | 148 | No | No | No | No | No | No | No | No | No | ## See also - CSS [`@media`](@media) at-rule - CSS [`@import`](@import) at-rule - [Responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) - [CSS media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Media_queries) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@custom-media](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@custom-media) --- ## Section: at-rules/@document # `@document` CSS at-rule **Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the [compatibility table](#browser_compatibility) at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time. **Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future. **Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future. The **`@document`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) restricts the style rules contained within it based on the URL of the document. It is designed primarily for user-defined style sheets (see [userchrome.org](https://www.userchrome.org/) for more information), though it can be used on author-defined style sheets, too. ## Syntax ``` @document url("https://www.example.com/") { h1 { color: green; } } ``` An `@document` rule can specify one or more matching functions. If any of the functions apply to a given URL, the rule will take effect on that URL. The functions available are: [`url()`](#url) Matches an exact URL. [`url-prefix()`](#url-prefix) Matches if the document URL starts with the value provided. [`domain()`](#domain) Matches if the document URL is on the domain provided (or a subdomain of it). [`media-document()`](#media-document) Matches the media according to the string in parameter, one of `video`, `image`, `plugin` or `all`. [`regexp()`](#regexp) Matches if the document URL is matched by the [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) provided. The expression must match the entire URL. The values provided to the `url()`, `url-prefix()`, `domain()`, and `media-document()` functions can be optionally enclosed by single or double quotes. The values provided to the `regexp()` function *must* be enclosed in quotes. Escaped values provided to the `regexp()` function must additionally be escaped from the CSS. For example, a `.` (period) matches any character in regular expressions. To match a literal period, you would first need to escape it using regular expression rules (to `\.`), then escape that string using CSS rules (to `\\.`). `@document` is currently only supported in Firefox; if you wanted to replicate using such functionality in your own non-Firefox browser, you could try using [this polyfill](https://github.com/An-Error94/Handy-Scripts/tree/master/%40document-polyfill) by @An-Error94, which uses a combination of a user script, [data-* attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/data-*), and [attribute selectors](../selectors/attribute_selectors). **Note:** There is a -moz-prefixed version of this property — `@-moz-document`. This has been limited to use only in user and UA sheets in Firefox 59 in Nightly and Beta — an experiment designed to mitigate potential CSS injection attacks (See [Firefox bug 1035091](https://bugzil.la/1035091)). ## Formal syntax ``` @document [ | url-prefix() | domain() | media-document() | regexp() ]# { } ``` ## Examples ### Specifying document for CSS rule ``` @document url("http://www.w3.org/"), url-prefix("http://www.w3.org/Style/"), domain("mozilla.org"), media-document("video"), regexp("https:.*") { /* CSS rules here apply to: - The page "http://www.w3.org/" - Any page whose URL begins with "http://www.w3.org/Style/" - Any page whose URL's host is "mozilla.org" or ends with ".mozilla.org" - Any standalone video - Any page whose URL starts with "https:" */ /* Make the above-mentioned pages really ugly */ body { color: purple; background: yellow; } } ``` ## Specifications [Initially](https://www.w3.org/TR/2012/WD-css3-conditional-20120911/#at-document) in Level 3, `@document` was [postponed](https://www.w3.org/TR/2012/WD-css3-conditional-20121213/#changes) to Level 4, but then subsequently removed. ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `document` | No | No | 61Only supports an empty `url-prefix()` value, which is supported due to its [use in Firefox browser detection](https://css-tricks.com/snippets/css/css-hacks-targeting-firefox/). Still supported in user stylesheets.1.5–61 | No | No | No | 61Only supports an empty `url-prefix()` value, which is supported due to its [use in Firefox for Android browser detection](https://css-tricks.com/snippets/css/css-hacks-targeting-firefox/). Still supported in user stylesheets.4–61 | No | No | No | No | No | ## See also - [Per-site user style sheet rules](https://lists.w3.org/Archives/Public/www-style/2004Aug/0135) on the www-style mailing list. © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@document](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@document) --- ## Section: at-rules/@font-face # `@font-face` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2016. The **`@font-face`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) specifies a custom font with which to display text; the font can be loaded from either a remote server or a locally-installed font on the user's own computer. ## Syntax ``` @font-face { font-family: "Trickster"; src: local("Trickster"), url("trickster-COLRv1.woff2") format("woff2") tech(color-COLRv1), url("trickster-outline.woff2") format("woff2"); } ``` ### Descriptors [`ascent-override`](@font-face/ascent-override) Defines the ascent metric for the font. [`descent-override`](@font-face/descent-override) Defines the descent metric for the font. [`font-display`](@font-face/font-display) Determines how a font face is displayed based on whether and when it is downloaded and ready to use. [`font-family`](@font-face/font-family) Specifies a name that will be used as the font face value for font properties. A `font-family` name is required for the `@font-face` rule to be valid. [`font-stretch`](@font-face/font-stretch) A [`font-stretch`](../properties/font-stretch) value. Accepts two values to specify a range that is supported by a font face, for example `font-stretch: 50% 200%;` [`font-style`](@font-face/font-style) A [`font-style`](../properties/font-style) value. Accepts two values to specify a range that is supported by a font face, for example `font-style: oblique 20deg 50deg;` [`font-weight`](@font-face/font-weight) A [`font-weight`](../properties/font-weight) value. Accepts two values to specify a range that is supported by a font face, for example `font-weight: 100 400;` [`font-feature-settings`](@font-face/font-feature-settings) Allows control over advanced typographic features in OpenType fonts. [`font-variation-settings`](@font-face/font-variation-settings) Allows low-level control over OpenType or TrueType font variations, by specifying the four-letter axis names of the features to vary, along with their variation values. [`font-width`](@font-face/font-width) Allows authors to specify a normal, condensed, or expanded face for the specified fonts. [`line-gap-override`](@font-face/line-gap-override) Defines the line gap metric for the font. [`size-adjust`](@font-face/size-adjust) Defines a multiplier for glyph outlines and metrics associated with this font. This makes it easier to harmonize the designs of various fonts when rendered at the same font size. [`src`](@font-face/src) Specifies references to font resources including hints about the font format and technology. A `src` is required for the `@font-face` rule to be valid. [`unicode-range`](@font-face/unicode-range) The range of Unicode code points to be used from the font. ## Description It's common to use both `url()` and `local()` together, so that the user's installed copy of the font is used if available, falling back to downloading a copy of the font if it's not found on the user's device. If the `local()` function is provided, specifying a font name to look for on the user's device, and if the [user agent](https://developer.mozilla.org/en-US/docs/Glossary/user_agent) finds a match, that local font is used. Otherwise, the font resource specified using the `url()` function is downloaded and used. Browsers attempt to load resources in their list declaration order, so usually `local()` should be written before `url()`. Both functions are optional, so a rule block containing only one or more `local()` without `url()` is possible. If more specific fonts with `format()` or `tech()` values are desired, these should be listed *before* versions that don't have these values, as the less specific variant would otherwise be tried and used first. For web delivery, it's generally best to serve fonts in WOFF2 format, because it compresses fonts more efficiently than older formats like WOFF or OpenType, reducing file size and improving load times. WOFF2 is also well supported in modern browsers, making it a safe default choice for most websites. By allowing authors to provide their own fonts, `@font-face` makes it possible to design content without being limited to the so-called "web-safe" fonts (that is, the fonts that are so common that they're considered to be universally available). The ability to specify the name of a locally-installed font to look for and use makes it possible to customize the font beyond the basics while making it possible to do so without relying on an internet connection. **Note:** Fallback strategies for loading fonts on older browsers are described in the [`src` descriptor page](@font-face/src#specifying_fallbacks_for_older_browsers). The `@font-face` at-rule may be used not only at the top level of a CSS, but also inside any [CSS conditional-group at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules#at-rules_and_descriptors). ### Font MIME Types | Format | MIME type | | --- | --- | | TrueType | `font/ttf` | | OpenType | `font/otf` | | Web Open Font Format | `font/woff` | | Web Open Font Format 2 | `font/woff2` | ### Notes - Web fonts are subject to the same domain restriction (font files must be on the same domain as the page using them), unless [HTTP access controls](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) are used to relax this restriction. - `@font-face` cannot be declared within a CSS selector. For example, the following will not work: ``` .className { @font-face { font-family: "MyHelvetica"; src: local("Helvetica Neue Bold"), local("HelveticaNeue-Bold"), url("MgOpenModernaBold.woff2"); font-weight: bold; } } ``` ## Formal syntax ## Examples ### Specifying a downloadable font This example specifies a downloadable font to use, applying it to the entire body of the document: ``` This is Bitstream Vera Serif Bold. ``` ``` @font-face { font-family: "Bitstream Vera Serif Bold"; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2"); } body { font-family: "Bitstream Vera Serif Bold", serif; } ``` ### Specifying local font alternatives In this example, the user's local copy of "Helvetica Neue Bold" is used; if the user does not have that font installed (both the full font name and the Postscript name are tried), then the downloadable font named "MgOpenModernaBold.woff2" is used instead: ``` @font-face { font-family: "MyHelvetica"; src: local("Helvetica Neue Bold"), local("HelveticaNeue-Bold"), url("MgOpenModernaBold.woff2"); font-weight: bold; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-face-rule | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-face` | 1 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 2.2 | 2 | | `OpenType_CBDT_CBLC` | 66 | 79 | No | 53 | No | 66 | No | 47 | No | 9.0 | 66 | No | | `OpenType_COLRv0` | 53 | 79 | 31 | 40 | 11.1 | 53 | 31 | 41 | 11.3 | 6.0 | 53 | 11.3 | | `OpenType_COLRv1` | 98 | 98 | 107 | 84 | No | 98 | 107 | 68 | No | 18.0 | 98 | No | | `OpenType_SBIX` | 66 | 79 | No | 53 | 9.1 | 66 | No | 47 | 9.3 | 9.0 | 66 | 9.3 | | `OpenType_SVG` | No | No | 31 | No | 12.1 | No | 31 | No | 12.2 | No | No | 12.2 | | `SVG_fonts` | 1–38 | No | No | 15–25 | 3.1 | 18–38 | No | 14–25 | 3 | 1.0–3.0 | 4.4–38 | 3 | | `WOFF` | 6 | 12 | 3.5 | 11.1 | 5.1 | 18 | 4 | 11.1 | 5 | 1.0 | 4.4 | 5 | | `WOFF_2` | 36 | 14 | 39 | 23 | 10Supported only on macOS 10.12 (Sierra) and later. | 36 | 39 | 24 | 10 | 3.0 | 37 | 10 | | `ascent-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | | `descent-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | | `font-display` | 60 | 79 | 58 | 47 | 11.1 | 60 | 58 | 44 | 11.3 | 11.0 | 60 | 11.3 | | `font-family` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 2.2 | 2 | | `font-feature-settings` | 140 | 140 | 34The [ISO/IEC CD 14496-22 3rd edition](https://mpeg.chiariglione.org/standards/mpeg-4/open-font-format/text-isoiec-cd-14496-22-3rd-edition) suggests using the `ssty` feature to provide glyph variants more suitable for use in scripts (for example primes used as superscripts). Starting with Firefox 29, this is done automatically by the [MathML](https://developer.mozilla.org/docs/Web/MathML) rendering engine. The ISO/IEC CD 14496-22 3rd edition also suggests applying the `dtls` feature to letters when placing mathematical accents to get dotless forms (for example dotless i, j with a hat). Starting with Firefox 35, this is done automatically by the MathML rendering engine. You can override the default values determined by the MathML rendering engine with CSS.15From Firefox 4 to Firefox 14 (inclusive), Firefox supported an older, slightly different syntax. See [OpenType Font Feature support in Firefox 4](https://hacks.mozilla.org/2010/11/firefox-4-font-feature-support/). | 124 | 10 | 140 | 34The [ISO/IEC CD 14496-22 3rd edition](https://mpeg.chiariglione.org/standards/mpeg-4/open-font-format/text-isoiec-cd-14496-22-3rd-edition) suggests using the `ssty` feature to provide glyph variants more suitable for use in scripts (for example primes used as superscripts). Starting with Firefox for Android 29, this is done automatically by the [MathML](https://developer.mozilla.org/docs/Web/MathML) rendering engine. The ISO/IEC CD 14496-22 3rd edition also suggests applying the `dtls` feature to letters when placing mathematical accents to get dotless forms (for example dotless i, j with a hat). Starting with Firefox for Android 35, this is done automatically by the MathML rendering engine. You can override the default values determined by the MathML rendering engine with CSS.15From Firefox for Android 4 to Firefox for Android 14 (inclusive), Firefox for Android supported an older, slightly different syntax. See [OpenType Font Feature support in Firefox for Android 4](https://hacks.mozilla.org/2010/11/firefox-4-font-feature-support/). | 92 | 10 | 30.0 | 140 | 10 | | `font-stretch` | 62 | 17 | 62 | 49 | 10.1 | 62 | 62 | 41 | 10.3 | 6.0 | 62 | 10.3 | | `font-style` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 4.4 | 2 | | `font-variant` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 4.4 | 2 | | `font-variation-settings` | 140 | 140 | 62 | 124 | No | 140 | 62 | 92 | No | 30.0 | 140 | No | | `font-weight` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 4.4 | 2 | | `font-width` | No | No | No | No | 18.4 | No | No | No | 18.4 | No | No | 18.4 | | `line-gap-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | | `size-adjust` | 92 | 92 | 92 | 78 | 17 | 92 | 92 | No | 17 | 16.0 | 92 | 17 | | `src` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 2.2 | 2 | | `unicode-range` | 1 | 12 | 36 | 15 | 3.1 | 18 | 36 | 14 | 3 | 1.0 | 4.4 | 3 | ## See also - [About WOFF](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Fonts/WOFF) - [Transfonter webfont generator](https://transfonter.org/) - [Beautiful fonts with @font-face](https://hacks.mozilla.org/2009/06/beautiful-fonts-with-font-face/) - [Font Library](https://fontlibrary.org/) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face) --- ## Section: at-rules/@font-face/ascent-override # `ascent-override` CSS at-rule descriptor Baseline Limited availability This feature is not Baseline because it does not work in some of the most widely-used browsers. The **`ascent-override`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor for the [`@font-face`](../@font-face) at-rule defines the ascent metric for the font. The ascent metric is the height above the baseline that CSS uses to lay out line boxes in an inline formatting context. ## Syntax ``` ascent-override: normal; ascent-override: 90%; ``` ### Values [`normal`](#normal) The default value. When used the metric value is obtained from the font file. ` ` A [``](../../values/percentage) value. ## Formal definition ## Formal syntax ## Examples ### Overriding metrics of a fallback font The `ascent-override` property can help when overriding the metrics of a fallback font to better match those of a primary web font. ``` @font-face { font-family: "web-font"; src: url("https://example.com/font.woff"); } @font-face { font-family: "local-font"; src: local("Local Font"); ascent-override: 125%; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-metrics-override-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `ascent-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | ## See also - [`descent-override`](descent-override) - [`font-display`](font-display) - [`font-family`](font-family) - [`font-weight`](font-weight) - [`font-style`](font-style) - [`font-stretch`](font-stretch) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`line-gap-override`](line-gap-override) - [`src`](src) - [`size-adjust`](size-adjust) - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/ascent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/ascent-override) --- ## Section: at-rules/@font-face/descent-override # `descent-override` CSS at-rule descriptor Baseline Limited availability This feature is not Baseline because it does not work in some of the most widely-used browsers. The **`descent-override`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor for the [`@font-face`](../@font-face) at-rule defines the descent metric for the font. The descent metric is the height below the baseline that CSS uses to lay out line boxes in an inline formatting context. ## Syntax ``` descent-override: normal; descent-override: 90%; ``` ### Values [`normal`](#normal) The default value. When used the metric value is obtained from the font file. ` ` A [``](../../values/percentage) value. ## Formal definition ## Formal syntax ## Examples ### Overriding metrics of a fallback font The `descent-override` property can help when overriding the metrics of a fallback font to better match those of a primary web font. ``` @font-face { font-family: "web-font"; src: url("https://example.com/font.woff"); } @font-face { font-family: "local-font"; src: local("Local Font"); descent-override: 125%; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-metrics-override-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `descent-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | ## See also - [`ascent-override`](ascent-override) - [`font-display`](font-display) - [`font-family`](font-family) - [`font-weight`](font-weight) - [`font-style`](font-style) - [`font-stretch`](font-stretch) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`line-gap-override`](line-gap-override) - [`src`](src) - [`size-adjust`](size-adjust) - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/descent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/descent-override) --- ## Section: at-rules/@font-face/font-display # `font-display` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since January 2020. The **`font-display`** descriptor for the [`@font-face`](../@font-face) at-rule determines how a font face is displayed based on whether and when it is downloaded and ready to use. ## Syntax ``` /* Keyword values */ font-display: auto; font-display: block; font-display: swap; font-display: fallback; font-display: optional; ``` ### Values [`auto`](#auto) The font display strategy is defined by the user agent. [`block`](#block) Gives the font face a short block period and an infinite swap period. [`swap`](#swap) Gives the font face an extremely small block period and an infinite swap period. [`fallback`](#fallback) Gives the font face an extremely small block period and a short swap period. [`optional`](#optional) Gives the font face an extremely small block period and no swap period. **Note:** In Firefox, the preferences `gfx.downloadable_fonts.fallback_delay` and `gfx.downloadable_fonts.fallback_delay_short` provide the duration of the "short" and "extremely small" periods, respectively. ## Description The font display timeline is based on a timer that begins the moment the user agent attempts to use a given downloaded font face. The timeline is divided into the three periods below which dictate the rendering behavior of any elements using the font face: - Font block period: If the font face is not loaded, any element attempting to use it must render an *invisible* fallback font face. If the font face successfully loads during this period, it is used normally. - Font swap period: If the font face is not loaded, any element attempting to use it must render a fallback font face. If the font face successfully loads during this period, it is used normally. - Font failure period: If the font face is not loaded, the user agent treats it as a failed load causing normal font fallback. ## Formal definition ## Formal syntax ## Examples ### Specifying fallback font-display ``` @font-face { font-family: "ExampleFont"; src: url("/path/to/fonts/example-font.woff2") format("woff2"); font-weight: normal; font-style: normal; font-display: fallback; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-display-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-display` | 60 | 79 | 58 | 47 | 11.1 | 60 | 58 | 44 | 11.3 | 11.0 | 60 | 11.3 | ## See also - [`font-family`](font-family) - [`font-stretch`](font-stretch) - [`font-style`](font-style) - [`font-weight`](font-weight) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) - [`unicode-range`](unicode-range) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-display) --- ## Section: at-rules/@font-face/font-family # `font-family` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2016. The **`font-family`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor sets the font family for a font specified in an [`@font-face`](../@font-face) at-rule. The value is used for name matching against a particular `@font-face` when styling elements using the [`font-family`](../../properties/font-family) property. Any name may be used, and this overrides any name specified in the underlying font data. ## Syntax ``` /* values */ font-family: "font family"; font-family: "another font family"; /* value */ font-family: example-font; ``` ### Values [``](#<family-name>) Specifies the name of the font family. ## Formal definition ## Formal syntax ## Examples ### Setting the font family name ``` @font-face { font-family: "Some font family"; src: url("some_font_name.ttf"); } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-family-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-family` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 2.2 | 2 | ## See also - [`font-display`](font-display) - [`font-stretch`](font-stretch) - [`font-style`](font-style) - [`font-weight`](font-weight) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) - [`unicode-range`](unicode-range) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-family) --- ## Section: at-rules/@font-face/font-feature-settings # `font-feature-settings` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since April 2017. The **`font-feature-settings`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor allows you to define the initial settings to use for the font defined by the [`@font-face`](../@font-face) at-rule. You can further use this descriptor to control typographic font features such as ligatures, small caps, and swashes, for the font defined by `@font-face`. The values for this descriptor are the same as the [`font-feature-settings`](../../properties/font-feature-settings) property, except for the global keyword values. Since this descriptor sets feature values on the font object in the `@font-face` at-rule and not on an entire element, only some glyphs in an element may be rendered using this descriptor. ## Syntax ``` /* Use the default settings */ font-feature-settings: normal; /* Set values for OpenType feature tags */ font-feature-settings: "smcp"; font-feature-settings: "smcp" on; font-feature-settings: "swsh" 2; ``` ### Values This descriptor is specified as either the keyword `normal` or as a comma-separated list of `` values. When rendering text, the list of OpenType `` values are passed to the text layout engine to enable or disable font features. [`normal`](#normal) Indicates that text is laid out using default font settings. This is the default value. [``](#<feature-tag-value>) Represents a space-separated tuple consisting of a tag name and an optional value. The tag name is always a [``](../../values/string) of four [ASCII](https://developer.mozilla.org/en-US/docs/Glossary/ASCII) characters. If the tag name has more or fewer characters or if it contains characters outside the `U+20` – `U+7E` code point range, the descriptor is invalid. The optional value can be a positive integer or the keyword `on` or `off`. The keywords `on` and `off` are synonyms for the values `1` and `0`, respectively. If no value is set, the default is `1`. For non-boolean OpenType features (e.g., [stylistic alternates](https://learn.microsoft.com/en-ca/typography/opentype/spec/features_pt#tag-salt)), the value implies a particular glyph to be selected; for boolean features, the value turns the feature on or off. ## Formal definition ## Formal syntax ## Examples ### Enabling swash glyphs using the @font-face at-rule In this example, the tag name `swsh` and a boolean value `1` are used as the value for the `font-feature-settings` descriptor in the `@font-face` at-rule. #### HTML ``` Swash is off here Swash is on here ``` #### CSS ``` @font-face { font-family: "MonteCarlo"; src: url("/shared-assets/fonts/monte-carlo/monte-carlo-regular.woff2"); } @font-face { font-family: "MonteCarlo2"; src: url("/shared-assets/fonts/monte-carlo/monte-carlo-regular.woff2"); font-feature-settings: "swsh" 1; } p { font-size: 3rem; margin: 0.7rem 3rem; } .swash-off { font-family: "MonteCarlo", cursive; } .swash-on { font-family: "MonteCarlo2", cursive; } ``` #### Result Line 1 shows the default ornate design of the [MonteCarlo](https://github.com/googlefonts/monte-carlo) font, and line 2 shows the default glyphs being replaced with [swash](https://learn.microsoft.com/en-ca/typography/opentype/spec/features_pt#tag-swsh) glyphs. ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-rend-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-feature-settings` | 140 | 140 | 34The [ISO/IEC CD 14496-22 3rd edition](https://mpeg.chiariglione.org/standards/mpeg-4/open-font-format/text-isoiec-cd-14496-22-3rd-edition) suggests using the `ssty` feature to provide glyph variants more suitable for use in scripts (for example primes used as superscripts). Starting with Firefox 29, this is done automatically by the [MathML](https://developer.mozilla.org/docs/Web/MathML) rendering engine. The ISO/IEC CD 14496-22 3rd edition also suggests applying the `dtls` feature to letters when placing mathematical accents to get dotless forms (for example dotless i, j with a hat). Starting with Firefox 35, this is done automatically by the MathML rendering engine. You can override the default values determined by the MathML rendering engine with CSS.15From Firefox 4 to Firefox 14 (inclusive), Firefox supported an older, slightly different syntax. See [OpenType Font Feature support in Firefox 4](https://hacks.mozilla.org/2010/11/firefox-4-font-feature-support/). | 124 | 10 | 140 | 34The [ISO/IEC CD 14496-22 3rd edition](https://mpeg.chiariglione.org/standards/mpeg-4/open-font-format/text-isoiec-cd-14496-22-3rd-edition) suggests using the `ssty` feature to provide glyph variants more suitable for use in scripts (for example primes used as superscripts). Starting with Firefox for Android 29, this is done automatically by the [MathML](https://developer.mozilla.org/docs/Web/MathML) rendering engine. The ISO/IEC CD 14496-22 3rd edition also suggests applying the `dtls` feature to letters when placing mathematical accents to get dotless forms (for example dotless i, j with a hat). Starting with Firefox for Android 35, this is done automatically by the MathML rendering engine. You can override the default values determined by the MathML rendering engine with CSS.15From Firefox for Android 4 to Firefox for Android 14 (inclusive), Firefox for Android supported an older, slightly different syntax. See [OpenType Font Feature support in Firefox for Android 4](https://hacks.mozilla.org/2010/11/firefox-4-font-feature-support/). | 92 | 10 | 30.0 | 140 | 10 | ## See also - Other `@font-face` descriptors: [`font-family`](font-family), [`font-style`](font-style), [`font-variation-settings`](font-variation-settings), [`font-weight`](font-weight), [`src`](src) - Related font properties: [`font-feature-settings`](../../properties/font-feature-settings), [`font-variant-alternates`](../../properties/font-variant-alternates), [`font-variation-settings`](../../properties/font-variation-settings) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-feature-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-feature-settings) --- ## Section: at-rules/@font-face/font-stretch # `font-stretch` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since January 2020. **Note:** The `font-stretch` descriptor was renamed to [`font-width`](font-width) in the [CSS Fonts specification](https://drafts.csswg.org/css-fonts/#font-stretch-desc). To preserve compatibility, the specification retains `font-stretch` as a legacy alias for the `font-width` descriptor. The **`font-stretch`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor allows authors to specify a normal, condensed, or expanded face for the fonts specified in the [`@font-face`](../@font-face) at-rule. For a particular font family, authors can download various font faces corresponding to the different styles of the same font family, and then use the `font-stretch` descriptor to specify the font face's stretch explicitly. ## Syntax ``` /* Single values */ font-stretch: ultra-condensed; font-stretch: extra-condensed; font-stretch: condensed; font-stretch: semi-condensed; font-stretch: normal; font-stretch: semi-expanded; font-stretch: expanded; font-stretch: extra-expanded; font-stretch: ultra-expanded; font-stretch: 50%; font-stretch: 100%; font-stretch: 200%; /* Multiple values */ font-stretch: 75% 125%; font-stretch: condensed ultra-condensed; ``` The `font-stretch` descriptor can take a single value from the list below. ### Values [`normal`](#normal) Specifies a normally condensed font face. [`semi-condensed`](#semi-condensed), `condensed`, `extra-condensed`, `ultra-condensed` Specifies a more condensed font face than normal, with ultra-condensed being the most condensed. [`semi-expanded`](#semi-expanded), `expanded`, `extra-expanded`, `ultra-expanded` Specifies a more expanded font face than normal, with ultra-expanded being the most expanded. ` ` A [``](../../values/percentage) value between 50% and 200% (inclusive). Negative values are not allowed for this descriptor. In earlier versions of the `font-stretch` specification, the descriptor accepts only the nine keyword values. CSS Fonts Level 4 extends the syntax to accept a `` value as well. This enables variable fonts to offer a continuous variation of character widths. For TrueType or OpenType variable fonts, the `wdth` variation is used to implement varying widths. If the font does not provide a face that exactly matches the given value, then values less than `100%` map to a condensed face, and values greater than or equal to `100%` map to an expanded face. ### Keyword to numeric mapping The table below shows the mapping between keyword values and numeric percentages: | Keyword | Percentage | | --- | --- | | `ultra-condensed` | 50% | | `extra-condensed` | 62.5% | | `condensed` | 75% | | `semi-condensed` | 87.5% | | `normal` | 100% | | `semi-expanded` | 112.5% | | `expanded` | 125% | | `extra-expanded` | 150% | | `ultra-expanded` | 200% | ### Variable fonts Most fonts have a particular width that corresponds to one of the keyterm values. However, variable fonts can support a range of widths with fine granularity, giving the designer a greater degree of control over the chosen weight. For this, percentage ranges are useful. For TrueType or OpenType variable fonts, the `wdth` variation is used to implement varying glyph widths. ## Accessibility People with dyslexia and other cognitive conditions may have difficulty reading fonts that are too condensed, especially if the font has a [low color contrast ratio](../../properties/color#accessibility). - [MDN Understanding WCAG, Guideline 1.4 explanations](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - | [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) | | --- | --- | ## Formal definition ## Formal syntax ## Examples ### Setting a percentage range for font-stretch The following example uses the [League Mono](https://www.theleagueofmoveabletype.com/league-mono) font. It synthesizes different font families from the same font file using the `font-stretch` descriptor with different keywords and percentages. ``` League Mono League Mono League Mono ``` ``` @font-face { font-family: "League Mono Ultra Condensed"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-stretch: ultra-condensed; /* same as 50% */ } @font-face { font-family: "League Mono Normal"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-stretch: 100%; /* same as normal */ } @font-face { font-family: "League Mono Ultra Expanded"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-stretch: ultra-expanded; /* same as 200% */ } p:nth-child(1) { font-family: "League Mono Ultra Condensed", sans-serif; } p:nth-child(2) { font-family: "League Mono Normal", sans-serif; } p:nth-child(3) { font-family: "League Mono Ultra Expanded", sans-serif; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-stretch-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-stretch` | 62 | 17 | 62 | 49 | 10.1 | 62 | 62 | 41 | 10.3 | 6.0 | 62 | 10.3 | ## See also - Modern [`font-width`](font-width) descriptor, replacing `font-stretch` - [`font-display`](font-display) descriptor - [`font-family`](font-family) descriptor - [`font-weight`](font-weight) descriptor - [`font-style`](font-style) descriptor - [`font-feature-settings`](../../properties/font-feature-settings) descriptor - [`font-variation-settings`](font-variation-settings) descriptor - [`src`](src) descriptor - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-stretch](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-stretch) --- ## Section: at-rules/@font-face/font-style # `font-style` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since July 2015. The **`font-style`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor allows authors to specify font styles for the fonts specified in the [`@font-face`](../@font-face) at-rule. For a particular font family, authors can download various font faces that correspond to the different styles of the same font family and then use the `font-style` descriptor to explicitly specify the font face's style. The values for this CSS descriptor are the same as that of the corresponding [`font-style`](../../properties/font-style) property. ## Syntax ``` font-style: normal; font-style: italic; font-style: oblique; font-style: oblique 30deg; font-style: oblique 30deg 50deg; ``` ### Values [`normal`](#normal) Selects the normal version of the font-family. [`italic`](#italic) Specifies that font-face is an italicized version of the normal font. [`oblique`](#oblique) Specifies that the font-face is an artificially sloped version of the normal font. [`oblique`](#oblique_2) with angle Selects a font classified as `oblique`, and additionally specifies an angle for the slant of the text. [`oblique`](#oblique_3) with angle range Selects a font classified as `oblique`, and additionally specifies a range of allowable angle for the slant of the text. Note that a range is only supported when the `font-style` is `oblique`; for `font-style: normal` or `italic`, no second value is allowed. ## Formal definition ## Formal syntax ## Examples ### Specifying an italic font style As an example, consider the garamond font family, in its normal form, we get the following result: ``` @font-face { font-family: "garamond"; src: url("garamond.woff2"); } ``` The italicized version of this text uses the same glyphs present in the unstyled version, but they are artificially sloped by a few degrees. On the other hand, if a true italicized version of the font family exists, we can include it in the `src` descriptor and specify the font style as italic, so that it is clear that the font is italicized. True italics use different glyphs and are a bit different from their upright counterparts, having some unique features and generally have a rounded and calligraphic quality. These fonts are specially created by font designers and are **not** artificially sloped. ``` @font-face { font-family: "garamond"; src: url("garamond-italic.woff2"); font-style: italic; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-prop-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-style` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 4.4 | 2 | ## See also - [`font-display`](font-display) - [`font-family`](font-family) - [`font-stretch`](font-stretch) - [`font-weight`](font-weight) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) - [`unicode-range`](unicode-range) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-style) --- ## Section: at-rules/@font-face/font-variation-settings # `font-variation-settings` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2018. The **`font-variation-settings`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor allows authors to specify low-level OpenType or TrueType font variations in the [`@font-face`](../@font-face) at-rule. The values for this descriptor are the same as the [`font-variation-settings`](../../properties/font-variation-settings) property, except for the global keyword values. Since this descriptor sets variation values on the font object in the `@font-face` at-rule and not on an entire element, only some glyphs in an element may be rendered using this descriptor. ## Syntax ``` /* Use the default settings */ font-variation-settings: normal; /* Set values for OpenType axis names */ font-variation-settings: "xhgt" 0.7; ``` ### Values [`normal`](#normal) Text is laid out using default settings. [` `](#<string>_<number>) When rendering text, the list of OpenType axis names is passed to the text layout engine to enable or disable font features. Each setting is always a [``](../../values/string) of 4 [ASCII](https://developer.mozilla.org/en-US/docs/Glossary/ASCII) characters, followed by a [``](../../values/number) indicating the axis value. If the `` has more or fewer characters or contains characters outside the U+20 - U+7E code point range, the whole property is invalid. The `` can be fractional or negative. ## Formal definition ## Formal syntax ## Examples ### Setting font weight and stretch in a @font-face rule ``` @font-face { font-family: "OpenTypeFont"; src: url("open_type_font.woff2") format("woff2"); font-weight: normal; font-style: normal; font-variation-settings: "wght" 400, "wdth" 300; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-rend-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-variation-settings` | 140 | 140 | 62 | 124 | No | 140 | 62 | 92 | No | 30.0 | 140 | No | ## See also - Other `@font-face` descriptors: [`font-display`](font-display), [`font-family`](font-family), [`font-feature-settings`](../../properties/font-feature-settings), [`font-stretch`](font-stretch), [`font-style`](font-style), [`font-weight`](font-weight), [`src`](src), [`unicode-range`](unicode-range) - Related font properties: [`font-feature-settings`](../../properties/font-feature-settings), [`font-variation-settings`](../../properties/font-variation-settings) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-variation-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-variation-settings) --- ## Section: at-rules/@font-face/font-weight # `font-weight` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since July 2015. The **`font-weight`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [`@font-face`](../@font-face) descriptor enables authors to specify a single font weight, or a range of font weights, for the font specified in a [`@font-face`](../@font-face) at-rule. This is then used by the browser to select the appropriate font when a CSS rule sets a desired [font weight](../../properties/font-weight). Typically, a developer will want to use fonts from a single font family in a range of different weights. With traditional, or *static* fonts, a single font file contains characters from a font family in a specific weight and style: for example, "Helvetica bold italic". To enable displaying light, regular, bold, or extra-bold fonts when the `font-weight` property calls a specific weight, you can define multiple [`@font-face`](../@font-face) at-rules for the same family (all with the same [`font-family`](font-family) descriptor value), one for each weight or range of weights. To declare the font to be used for a range of font weights, declare a space-separated pair of font-weight values as the value for the `font-weight` descriptor. When CSS rules set a font weight by setting the [`font-weight`](../../properties/font-weight) property or the [`font`](../../properties/font) shorthand property, the appropriate font will then be used. For example, if the descriptor is `font-weight: 400 600;`, when the property is `font-weight: 450` or `font-weight: 550`, that font will be used for that font-family. Whether the font is a static or a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Fonts/Variable_fonts), the font matching the range will be used. In this case, if the font is a static font, `450` and `550` will appear the same. If the font is a variable font, the latter will be bolder. The descriptor is the same for all fonts, but the range you'll set for a variable font will generally be greater, possibly even `1 1000` to use the same font for all font weight property values. ## Syntax ``` /* Single values */ font-weight: normal; font-weight: bold; font-weight: 400; /* Defining a range */ font-weight: normal bold; font-weight: 300 500; ``` ### Values The `font-weight` descriptor takes one of the following forms: - The keyword `auto`. - A single `` value. - A pair of `` values, separated by a space. Each `` may be any one of the following: [`normal`](#normal) Normal font weight. Same as `400`. [`bold`](#bold) Bold font weight. Same as `700`. [``](#<number>) A [``](../../values/number) value between 1 and 1000, inclusive. Higher numbers represent weights that are bolder than (or as bold as) lower numbers. Certain commonly used values correspond to common weight names, as described in the [Common weight name mapping](#common_weight_name_mapping) section below. ### Common weight name mapping The numerical values `100` to `900` roughly correspond to the following common weight names: | Value | Common weight name | | --- | --- | | 100 | Thin (Hairline) | | 200 | Extra Light (Ultra Light) | | 300 | Light | | 400 | Normal | | 500 | Medium | | 600 | Semi Bold (Demi Bold) | | 700 | Bold | | 800 | Extra Bold (Ultra Bold) | | 900 | Black (Heavy) | ### Variable fonts Most fonts have a particular weight which corresponds to one of the numbers in [Common weight name mapping](#common_weight_name_mapping). However some fonts, called variable fonts, can support a range of weights with more or less fine granularity, and this can give the designer a much closer degree of control over the chosen weight. For TrueType or OpenType variable fonts, the "wght" variation is used to implement varying weights. ## Accessibility People experiencing low vision conditions may have difficulty reading text set with a `font-weight` value of `100` (Thin/Hairline) or `200` (Extra Light), especially if the font has a [low contrast color ratio](../../properties/color#accessibility). - [MDN Understanding WCAG, Guideline 1.4 explanations](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - | [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) | | --- | --- | ## Formal definition ## Formal syntax ## Examples ### Selecting normal and bold fonts In this example we include two fonts, one normal weight, one bold weight, from the ["Fira Sans"](https://fonts.google.com/specimen/Fira+Sans) font family using two `@font-face` at rules. We set `font-weight` descriptors to match the weight of the fonts. After this, CSS rules can select the normal or the bold font for the "Fira Sans" family just by setting the [`font-weight`](../../properties/font-weight) property. Note that the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong) HTML element also selects the bold font, because by default `` elements have a CSS `font-weight` property value of `bold`. #### HTML ``` Fira Sans, `normal` weight paragraph Fira Sans, `bold` weight paragraph Fira Sans, <strong> element (`bold`) ``` #### CSS ``` @font-face { font-family: "Fira Sans"; font-weight: normal; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2"); } @font-face { font-family: "Fira Sans"; font-weight: bold; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Bold.woff2"); } body { font-family: "Fira Sans", serif; font-size: 2rem; } p.one { font-weight: normal; } p.two { font-weight: bold; } ``` #### Result ### Setting font-weight ranges This example demonstrates how authors can include multiple fonts for multiple font-weights (and font-styles), by including multiple `@font-face` declarations with the same `font-family` value. By setting the `font-weight` descriptors using ranges from 1 to 1000, in the rest of your stylesheets, you can declare a `font-weight` (or `font-style`), and know the appropriate font will be used. #### HTML ``` This has a font weight of 100 This has a font weight of 300 This has a font weight of 400 This has a font weight of 500 This has a font weight of 700 This has a font weight of 900 ``` #### CSS We include four `@font-face` declarations for four different fonts from the `FireSans` font family, as seen in the previous example. Each declaration is set to a different range of font-weight values, but all use the same font name. The first declaration uses `FiraSans-Regular` and its associated `font-weight` range includes the entire possible range of font weight values. The other three declarations use the light, bold, and extra-bold versions of the font, and their associated `font-weight` ranges define subsets of the range as follows: - the light font is associated with the range 1-300 - the bold font is associated with the range 500-700 - the extra-bold font is associated with the range 700-1000 The CSS [cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Introduction) ensures that the three latter declarations override parts of the range that was set in the `FiraSans-Regular` declaration. ``` @font-face { font-family: "Fira Sans"; font-weight: 1 1000; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2"); } @font-face { font-family: "Fira Sans"; font-weight: 1 300; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Light.woff2"); } @font-face { font-family: "Fira Sans"; font-weight: 500 700; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Bold.woff2"); } @font-face { font-family: "Fira Sans"; font-weight: 700 1000; src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-ExtraBold.woff2"); } body { font-family: "Fira Sans", serif; font-size: 2rem; } p.one { font-weight: 100; } p.three { font-weight: 300; } p.four { font-weight: 400; } p.five { font-weight: 500; } p.seven { font-weight: 700; } p.nine { font-weight: 900; } ``` #### Result The `seven` paragraph uses the extra bold font. While `font-weight: 700` matches both the `FiraSans-Bold` and `FiraSans-ExtraBold` declarations, as the FiraSans-ExtraBold is declared later, it overrides the `FiraSans-Bold` for that value. Similarly, the `100` and `300` both use the light font; although `FiraSans-Regular` and `FiraSans-Light` both include `300` in their ranges, `FiraSans-Light` is declared later. Alternatively, we could have declared `FiraSans-Regular` after `FiraSans-Light`, but we would need to change the `font-weight` descriptor range if we do so. ### Setting a range for a variable font In this example we're using the `font-weight` descriptor to restrict the range of weights that can be set when using a variable font. We include a variable font, ["League Mono"](https://www.theleagueofmoveabletype.com/league-mono), using a single `@font-face` at-rule. We use a `font-weight: 300 700` value to effectively limit the range of weights that are available. If a CSS rule uses our "League Mono" font, then if it specifies a weight outside this range the weight it gets is clamped to the range. #### HTML We include a paragraph with `` initially set to `400`, as that is the default font-weight for unstyled paragraph text. This paragraph is nestled between two other paragraphs, so you can compare rendered versus declared font weight values. We include an [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range) of type `range`, nested in a [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label), setting the `step` to `50`. ``` LeagueMono, font-weight: 300 (comparison) LeagueMono, font-weight: 400 (example) LeagueMono, font-weight: 700 (comparison) Change the font weight: ``` #### CSS We set the `font-weight` descriptor range to `300 700`, clamping the variable font to that range. ``` @font-face { font-family: "LeagueMono"; src: url("https://mdn.github.io/shared-assets/fonts/LeagueMono-VF.ttf"); font-weight: 300 700; } p { font-family: "LeagueMono", serif; font-size: 1.5rem; } p:first-of-type { font-weight: 300; } p:last-of-type { font-weight: 700; } ``` #### JavaScript We include an event handler that updates the paragraph's `font-weight` property value, and updates the text to reflect the change: ``` const text = document.querySelector("#example"); const log = document.querySelector("output"); const range = document.querySelector("input"); range.addEventListener("change", () => { text.style.fontWeight = range.value; log.innerText = range.value; }); ``` #### Result Change the font weight of the paragraph via the range. Note that the example paragraph does not get lighter than the `300` paragraph above it or bolder than the `700` paragraph below it; the font weight is clamped to the range defined by the `font-weight` descriptor. ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-prop-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-weight` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 4.4 | 2 | ## See also - [`font-display`](font-display) - [`font-family`](font-family) - [`font-stretch`](font-stretch) - [`font-style`](font-style) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-weight) --- ## Section: at-rules/@font-face/font-width # `font-width` CSS at-rule descriptor Baseline Limited availability This feature is not Baseline because it does not work in some of the most widely-used browsers. **Experimental:** **This is an experimental technology** Check the [Browser compatibility table](#browser_compatibility) carefully before using this in production. **Experimental:** **This is an experimental technology** Check the [Browser compatibility table](#browser_compatibility) carefully before using this in production. **Note:** The `font-width` descriptor is the modern replacement for the [`font-stretch`](font-stretch) descriptor, which is a legacy alias. While `font-width` is the specification's preferred name, `font-stretch` currently has broader browser support. Check the [fallback example](#providing_a_font-stretch_fallback) and [browser compatibility](#browser_compatibility) table for details. The **`font-width`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor allows authors to specify a normal, condensed, or expanded face for the fonts specified in the [`@font-face`](../@font-face) at-rule. For a particular font family, authors can download various font faces corresponding to the different styles of the same font family, and then use the `font-width` descriptor to specify the font face's width explicitly. The available `font-width` descriptor values are the same as those of the corresponding [`font-width`](../../properties/font-width) property. ## Syntax ``` /* Single values */ font-width: ultra-condensed; font-width: extra-condensed; font-width: condensed; font-width: semi-condensed; font-width: normal; font-width: semi-expanded; font-width: expanded; font-width: extra-expanded; font-width: ultra-expanded; font-width: 50%; font-width: 100%; font-width: 200%; /* Multiple values */ font-width: 75% 125%; font-width: condensed ultra-condensed; ``` The `font-width` descriptor can take a single value from the list below. ### Values [`normal`](#normal) Specifies a normally condensed font face. [`semi-condensed`](#semi-condensed), `condensed`, `extra-condensed`, `ultra-condensed` Specifies a more condensed font face than normal, with ultra-condensed being the most condensed. [`semi-expanded`](#semi-expanded), `expanded`, `extra-expanded`, `ultra-expanded` Specifies a more expanded font face than normal, with ultra-expanded being the most expanded. ` ` A [``](../../values/percentage) value between 50% and 200% (inclusive). Negative values are not allowed for this descriptor. In earlier versions of the `font-width` specification, the descriptor accepts only the nine keyword values. CSS Fonts Level 4 extends the syntax to accept a `` value as well. This enables variable fonts to offer a continuous variation of character widths. For TrueType or OpenType variable fonts, the `wdth` variation is used to implement varying widths. If the font does not provide a face that exactly matches the given value, then values less than `100%` map to a condensed face, and values greater than or equal to `100%` map to an expanded face. ### Keyword to numeric mapping The table below shows the mapping between keyword values and numeric percentages: | Keyword | Percentage | | --- | --- | | `ultra-condensed` | 50% | | `extra-condensed` | 62.5% | | `condensed` | 75% | | `semi-condensed` | 87.5% | | `normal` | 100% | | `semi-expanded` | 112.5% | | `expanded` | 125% | | `extra-expanded` | 150% | | `ultra-expanded` | 200% | ### Variable fonts Most fonts have a particular width that corresponds to one of the keyterm values. However, variable fonts can support a range of widths with fine granularity, giving the designer a greater degree of control over the chosen weight. For this, percentage ranges are useful. For TrueType or OpenType variable fonts, the `wdth` variation is used to implement varying glyph widths. ## Accessibility People with dyslexia and other cognitive conditions may have difficulty reading fonts that are too condensed, especially if the font has a [low color contrast ratio](../../properties/color#accessibility). - [MDN Understanding WCAG, Guideline 1.4 explanations](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - | [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) | | --- | --- | ## Formal definition ## Formal syntax ## Examples ### Setting a percentage range for font-width The following example uses the [League Mono](https://www.theleagueofmoveabletype.com/league-mono) font. It synthesizes different font families from the same font file using the `font-width` descriptor with different keywords and percentages. ``` League Mono League Mono League Mono ``` ``` @font-face { font-family: "League Mono Ultra Condensed"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-width: ultra-condensed; /* same as 50% */ } @font-face { font-family: "League Mono Normal"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-width: 100%; /* same as normal */ } @font-face { font-family: "League Mono Ultra Expanded"; src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); font-width: ultra-expanded; /* same as 200% */ } p:nth-child(1) { font-family: "League Mono Ultra Condensed", sans-serif; } p:nth-child(2) { font-family: "League Mono Normal", sans-serif; } p:nth-child(3) { font-family: "League Mono Ultra Expanded", sans-serif; } ``` ### Providing a font-stretch fallback Because `font-width` does not yet have broad browser support, you may want to include the legacy [`font-stretch`](font-stretch) descriptor as a fallback. Place `font-stretch` before `font-width` so that supporting browsers use the modern descriptor: ``` @font-face { font-family: "MyFont"; src: url("my-font.woff2") format("woff2"); font-stretch: condensed; /* for browsers that don't support font-width */ font-width: condensed; } ``` **Note:** You can automate this fallback pattern using the [postcss-preset-env](https://preset-env.cssdb.org/) plugin for PostCSS, which includes the [postcss-font-width-property](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-font-width-property) transform to convert `font-width` declarations to `font-stretch` automatically. ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # descdef-font-face-font-width | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-width` | No | No | No | No | 18.4 | No | No | No | 18.4 | No | No | 18.4 | ## See also - Legacy [`font-stretch`](font-stretch) alias descriptor with better browser support - [`font-display`](font-display) descriptor - [`font-family`](font-family) descriptor - [`font-weight`](font-weight) descriptor - [`font-style`](font-style) descriptor - [`font-feature-settings`](../../properties/font-feature-settings) property - [`font-variation-settings`](font-variation-settings) descriptor - [`src`](src) descriptor - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-width](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-width) --- ## Section: at-rules/@font-face/line-gap-override # `line-gap-override` CSS at-rule descriptor Baseline Limited availability This feature is not Baseline because it does not work in some of the most widely-used browsers. The **`line-gap-override`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor for the [`@font-face`](../@font-face) at-rule defines the line-gap metric for the font. The line-gap metric is the font recommended line-gap or external leading. ## Syntax ``` line-gap-override: normal; line-gap-override: 90%; ``` ### Values [`normal`](#normal) The default value. When used the metric value is obtained from the font file. ` ` A [``](../../values/percentage) value. ## Formal definition ## Formal syntax ## Examples ### Overriding metrics of a fallback font The `line-gap-override` property can help when overriding the metrics of a fallback font to better match those of a primary web font. ``` @font-face { font-family: "web-font"; src: url("https://example.com/font.woff"); } @font-face { font-family: "local-font"; src: local("Local Font"); line-gap-override: 125%; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-metrics-override-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `line-gap-override` | 87 | 87 | 89 | 73 | preview | 87 | 89 | 62 | No | 14.0 | 87 | No | ## See also - [`descent-override`](descent-override) - [`font-display`](font-display) - [`font-family`](font-family) - [`font-weight`](font-weight) - [`font-style`](font-style) - [`font-stretch`](font-stretch) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) - [`size-adjust`](size-adjust) - [`unicode-range`](unicode-range) descriptor © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/line-gap-override](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/line-gap-override) --- ## Section: at-rules/@font-face/size-adjust # `size-adjust` CSS at-rule descriptor Baseline Newly available This feature works across the latest devices and browser versions. This feature might not work in older devices or browser versions. It's been available across browsers since July 2024. The **`size-adjust`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor for the [`@font-face`](../@font-face) at-rule defines a multiplier for glyph outlines and metrics associated with this font. This makes it easier to harmonize the designs of various fonts when rendered at the same font size. The `size-adjust` descriptor behaves in a similar fashion to the [`font-size-adjust`](../../properties/font-size-adjust) property. It calculates an adjustment per font by matching ex heights. ## Syntax ``` size-adjust: 90%; ``` ### Values ` ` A [``](../../values/percentage) value with an initial value of 100%. All metrics associated with this font are scaled by the given percentage. This includes glyph advances, baseline tables, and overrides provided by [`@font-face`](../@font-face) descriptors. ## Formal definition ## Formal syntax ## Examples ### Overriding metrics of a fallback font The `size-adjust` property can help when overriding the metrics of a fallback font to better match those of a primary web font. ``` @font-face { font-family: "web-font"; src: url("https://example.com/font.woff"); } @font-face { font-family: "local-font"; src: local("Local Font"); size-adjust: 90%; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 5 # size-adjust-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `size-adjust` | 92 | 92 | 92 | 78 | 17 | 92 | 92 | No | 17 | 16.0 | 92 | 17 | ## See also - [`font-display`](font-display) descriptor - [`font-family`](font-family) descriptor - [`font-weight`](font-weight) descriptor - [`font-style`](font-style) descriptor - [`font-stretch`](font-stretch) descriptor - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) descriptor - [`src`](src) descriptor - [`unicode-range`](unicode-range) descriptor - [`font-size-adjust`](../../properties/font-size-adjust) property © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/size-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/size-adjust) --- ## Section: at-rules/@font-face/src # `src` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2016. The **`src`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor for the [`@font-face`](../@font-face) at-rule specifies the resource containing font data. It is required for the `@font-face` rule to be valid. ## Syntax ``` /* values */ src: url("https://example.com/path/to/font.woff"); /* Absolute URL */ src: url("path/to/font.woff"); /* Relative URL */ src: url("path/to/svgFont.svg#example"); /* Fragment identifying font */ /* values */ src: local(font); /* Unquoted name */ src: local(some font); /* Name containing space */ src: local("font"); /* Quoted name */ src: local("some font"); /* Quoted name containing a space */ /* )> values */ src: url("path/to/fontCOLRv1.otf") tech(color-COLRv1); src: url("path/to/fontCOLR-svg.otf") tech(color-SVG); /* )> values */ src: url("path/to/font.woff") format("woff"); src: url("path/to/font.woff2") format("woff2"); /* Multiple resources */ src: url("path/to/font.woff") format("woff"), url("path/to/font.woff2") format("woff2"); /* Multiple resources with font format and technologies */ src: url("trickster-COLRv1.woff2") format("woff2") tech(color-COLRv1), url("trickster-outline.woff2") format("woff2"); ``` ### Values [`url()`](#url) Specifies an external reference consisting of a [``](../../values/url_value), followed by optional hints using the `format()` and `tech()` component values that specify the format and font technology of the resource referenced by the URL. The `format()` and `tech()` components are a comma-separated list of strings of known [font formats](#font_formats) and technologies. If a user agent doesn't support the font technology or formats, it skips downloading the font resource. If no format or technology hints are supplied, the font resource is always downloaded. [`format()`](#format) An optional declaration that follows the `url()` value that provides a hint for the user agent on the font format. If the value is not supported or invalid, the browser may not download the resource, potentially saving bandwidth. If omitted, the browser will download the resource and then detect the format. If including a font source for backward-compatibility that is not in the list of [defined keywords](#formal_syntax), enclose the format string in quotes. Possible values are described in the [Font formats](#font_formats) section below. [`tech()`](#tech) An optional declaration that follows the `url()` value that provides a hint for the user agent on the font technology. The value for `tech()` may be one of the keywords described in [Font technologies](#font_technologies). [`local()`](#local<font-face-name>) Specifies the font name should the font be available on the user's device. Enclosing the font name in quotes is optional. **Note:** For OpenType and TrueType fonts, `` is used to match either the Postscript name or the full font name in the name table of locally available fonts. Which type of name is used varies by platform and font, so you should include both of these names to assure proper matching across platforms. Platform substitutions for a given font name must not be used. **Note:** Locally available fonts may have been preinstalled on the user's device, or may have been actively installed by the user. While the set of preinstalled fonts is likely to be the same for all users of a particular device, the set of user-installed fonts is not. By discovering the set of user-installed fonts, a site can therefore build a [fingerprint](https://developer.mozilla.org/en-US/docs/Glossary/fingerprinting) for the device, helping the site to track users across the web. To prevent this, user agents may ignore user-installed fonts when using `local()`. [``](#<font-face-name>) Specifies the full name or postscript name of a locally-installed font face using the `local()` component value, which uniquely identifies a single font face within a larger family. The name can optionally be enclosed in quotes. The font face name [is not case-sensitive](https://drafts.csswg.org/css-fonts-3/#font-family-casing). **Note:** The [Local Font Access API](https://developer.mozilla.org/en-US/docs/Web/API/Local_Font_Access_API) can be used to access the user's locally installed font data — this includes higher-level details such as names, styles, and families, as well as the raw bytes of the underlying font files. ## Description The value of this descriptor is a prioritized, comma-separated list of external references or locally-installed font face names, where each resource is specified using `url()` or `local()`. When a font is needed, the [user agent](https://developer.mozilla.org/en-US/docs/Glossary/user_agent) iterates over the set of references listed using the first one it can successfully activate. Fonts containing invalid data or local font faces that are not found are ignored and the user agent loads the next font in the list. If multiple `src` descriptors are set, only the last declared rule that is able to load a resource is applied. If the last `src` descriptor can load a resource and doesn't include a `local()` font, the browser may download external font files and ignore the local version even if there is one available on the device. **Note:** Values within descriptors that the browser considers invalid are ignored. Some browsers will ignore the whole descriptor if any item is invalid, even if only one item is invalid. This may affect design of fallbacks. See [Browser compatibility](#browser_compatibility) for more information. As with other URLs in CSS, the URL may be relative, in which case it is resolved relative to the location of the style sheet containing the `@font-face` rule. In the case of SVG fonts, the URL points to an element within a document containing SVG font definitions. If the element reference is omitted, a reference to the first defined font is implied. Similarly, font container formats that can contain more than one font load only one of the fonts for a given `@font-face` rule. Fragment identifiers are used to indicate which font to load. If a container format lacks a defined fragment identifier scheme, a 1-based indexing scheme (e.g., "font-collection#1" for the first font, "font-collection#2" for the second font, etc.) is used. If the font file is a container for multiple fonts, a fragment identifier is included to indicate the sub-font that should be used, as shown below: ``` /* WhichFont is the PostScript name of a font in the font file */ src: url("collection.otc#WhichFont"); /* WhichFont is the element id of a font in the SVG Font file */ src: url("fonts.svg#WhichFont"); ``` ### Font formats The following table shows the valid font keywords and their corresponding font formats. To check if a font format is supported by a browser within CSS, use the [`@supports`](../@supports) rule. | Keyword | Font Format | Common extensions | | --- | --- | --- | | `collection` | OpenType Collection | .otc, .ttc | | `embedded-opentype` | Embedded OpenType | .eot | | `opentype` | OpenType | .otf, .ttf | | `svg` | SVG Font (deprecated) | .svg, .svgz | | `truetype` | TrueType | .ttf | | `woff` | WOFF 1.0 | .woff | | `woff2` | WOFF 2.0 | .woff2 | **Note:** - `format(svg)` stands for [SVG fonts](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Using_fonts), and `tech(color-SVG)` stands for [OpenType fonts with SVG table](https://learn.microsoft.com/en-us/typography/opentype/spec/svg) (also called OpenType-SVG color fonts), which are completely different. - The `opentype` and `truetype` values are equivalent whether the font file uses cubic bezier curves (within CFF/CFF2 table) or quadratic bezier curves (within glyph table). Older non-normalized `format()` values have the following equivalent syntax; provided as a string enclosed in quotes for backward-compatibility reasons: | Old syntax | Equivalent syntax | | --- | --- | | `format("woff2-variations")` | `format(woff2) tech(variations)` | | `format("woff-variations")` | `format(woff) tech(variations)` | | `format("opentype-variations")` | `format(opentype) tech(variations)` | | `format("truetype-variations")` | `format(truetype) tech(variations)` | ### Font technologies The following table shows valid values for the `tech()` descriptor and their corresponding font technologies. To check if a font technology is supported by a browser within CSS, use the [`@supports`](../@supports) at-rule. | Keyword | Description | | --- | --- | | `color-cbdt` | Color bitmap data tables | | `color-colrv0` | Multi-colored glyphs via COLR version 0 table | | `color-colrv1` | Multi-colored glyphs via COLR version 1 table | | `color-sbix` | Standard bitmap graphics tables | | `color-svg` | SVG multi-colored tables | | `features-aat` | TrueType `morx` and `kerx` tables | | `features-graphite` | Graphite features, namely `Silf`, `Glat`, `Gloc`, `Feat`, and `Sill` tables | | `features-opentype` | OpenType `GSUB` and `GPOS` tables | | `incremental` | Incremental font loading | | `palettes` | Font palettes by means of `font-palette` to select one of many color palettes in the font | | `variations` | Font variations in TrueType and OpenType fonts to control the font axis, weight, glyphs, etc. | ## Formal definition ## Formal syntax ``` ``` ## Examples ### Specifying font resources using url() and local() The example below shows how to define two font faces with the same font family. The `font-family` is named `MainText`. The first font face has a regular font, and the second one is a bold version of the same font family. ``` /* Defining a regular font face */ @font-face { font-family: "MainText"; src: local("Futura-Medium"), url("FuturaMedium.woff") format("woff"), url("FuturaMedium.woff2") format("woff2"); } /* Defining a different bold font face for the same family */ @font-face { font-family: "MainText"; src: local("Gill Sans Bold") /* full font name */, local("GillSans-Bold") /* postscript name */, url("GillSansBold.woff") format("woff"), url("GillSansBold.woff2") format("woff2"), url("GillSansBold.svg#MyFontBold"); /* Referencing an SVG font fragment by id */ font-weight: bold; } /* Using the regular font face */ p { font-family: "MainText", sans-serif; } /* Font-family is inherited, but bold fonts are used */ p.bold { font-weight: bold; } ``` ### Specifying font resources using tech() and format() values The following example shows how to use the `tech()` and `format()` values to specify font resources. A font using `color-colrv1` technology and `opentype` format is specified using the `tech()` and `format()` values. A color font will be activated if the user agent supports it, and an `opentype` non-color is provided as a fallback. ``` @font-face { font-family: "Trickster"; src: url("trickster-COLRv1.woff2") format("woff2") tech(color-COLRv1), url("trickster-outline.woff2") format("woff2"); } /* Using the font face */ p { font-family: "Trickster", fantasy; } ``` ### Specifying fallbacks for older browsers Browsers should use a `@font-face` with a single `src` descriptor listing possible sources for the font. Since the browser will use the first resource that it is able to load, items should be specified in the order of your preference for their usage. Generally this means that local files should appear before remote files and that resources with `format()` or `tech()` constraints should appear before resources that don't have them (otherwise the less-constrained version would always be selected). For example: ``` @font-face { font-family: "MgOpenModernaBold"; src: url("MgOpenModernaBoldIncr.woff2") format("woff2") tech(incremental), url("MgOpenModernaBold.woff2") format("woff2"); } ``` A browser that does not support `tech()` above should ignore the first item and attempt to load the second resource. Some browsers do not yet [ignore invalid items](#browser_compatibility), and instead fail the whole `src` descriptor if any value is invalid. If working with these browsers you can specify multiple `src` descriptors as fallbacks. Note that multiple `src` descriptors are attempted in reverse-order, so at the end we have our normal descriptor with all the items. ``` @font-face { font-family: "MgOpenModernaBold"; src: url("MgOpenModernaBold.woff2") format("woff2"); src: url("MgOpenModernaBoldIncr.woff2") format("woff2") tech(incremental); src: url("MgOpenModernaBoldIncr.woff2") format("woff2") tech(incremental), url("MgOpenModernaBold.woff2") format("woff2"); } ``` ### Checking if the user agent supports a font The following example shows how to check if the user agent supports a font technology using the [`@supports`](../@supports) rule. The block of CSS inside `@supports` will be applied if the user agent supports `color-COLRv1` technology. ``` @supports font-tech(color-COLRv1) { @font-face { font-family: "Trickster"; src: url("trickster-COLRv1.woff2") format("woff2") tech(color-COLRv1); } .colored_text { font-family: "Trickster", fantasy; } } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # src-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `src` | 4 | 12 | 3.5 | 10 | 3.1 | 18 | 4 | 10.1 | 2 | 1.0 | 2.2 | 2 | | `drop_invalid_item` | 108Chrome drops invalid item for `tech()` but not other invalid values | 108Edge drops invalid item for `tech()` but not other invalid values | 109 | 94Opera drops invalid item for `tech()` but not other invalid values | No | 108Chrome Android drops invalid item for `tech()` but not other invalid values | 109 | 73Opera Android drops invalid item for `tech()` but not other invalid values | No | 21.0Samsung Browser drops invalid item for `tech()` but not other invalid values | 108WebView Android drops invalid item for `tech()` but not other invalid values | No | | `format_keyword` | 108 | 108 | 105 | 94 | 4 | 108 | 105 | 73 | 5 | 21.0 | 108 | 5 | | `format_variations` | 66 | 17 | 62 | 53 | 11 | 66 | 62 | 47 | 11 | 9.0 | 66 | 11 | | `tech_keyword` | 108 | 108 | 107 | 94 | 17 | 108 | 107 | 73 | 17 | 21.0 | 108 | 17 | ## See also - [`@font-face`](../@font-face) - [`@supports`](../@supports) - [`font-display`](font-display) - [`font-family`](font-family) - [`font-stretch`](font-stretch) - [`font-style`](font-style) - [`font-weight`](font-weight) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`unicode-range`](unicode-range) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src) --- ## Section: at-rules/@font-face/unicode-range # `unicode-range` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2016. The **`unicode-range`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) descriptor sets the specific range of characters to be used from a font defined using the [`@font-face`](../@font-face) at-rule and made available for use on the current page. If the page doesn't use any character in this range, the font is not downloaded; if it uses at least one, the whole font is downloaded. ## Syntax ``` /* values */ unicode-range: U+26; /* single code point */ unicode-range: U+0-7F; unicode-range: U+0025-00FF; /* code point range */ unicode-range: U+4??; /* wildcard range */ unicode-range: U+0025-00FF, U+4??; /* multiple values */ ``` ### Values [***single code point***](#single_code_point) A single Unicode character code point, for example `U+26`. [***code point range***](#code_point_range) A range of Unicode code points. So for example, `U+0025-00FF` means *include all characters in the range `U+0025` to `U+00FF`*. [***wildcard range***](#wildcard_range) A range of Unicode code points containing wildcard characters, that is using the `'?'` character, so for example `U+4??` means *include all characters in the range `U+400` to `U+4FF`*. ## Description The purpose of this descriptor is to allow the font resources to be segmented so that a browser only needs to download the font resource needed for the text content of a particular page. For example, a site with many localizations could provide separate font resources for English, Greek and Japanese. For users viewing the English version of a page, the font resources for Greek and Japanese fonts wouldn't need to be downloaded, saving bandwidth. ## Formal definition ## Formal syntax ## Examples ### Using a different font for a single character In this example, we create a single [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div) element, with a text string that includes an ampersand that we want to style with a different font. To make it obvious, we will use a sans-serif font, *Helvetica*, for the text, and a serif font, *Times New Roman*, for the ampersand. In the CSS we are in effect defining a completely separate [`@font-face`](../@font-face) that only includes a single character in it, meaning that only this character will be styled with this font. We could also have done this by wrapping the ampersand in a [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) and applying a different font just to that, but that is an extra element and rule set. #### HTML ``` Me & You = Us ``` #### CSS ``` @font-face { font-family: "Ampersand"; src: local("Times New Roman"); unicode-range: U+26; } div { font-size: 4em; font-family: "Ampersand", "Helvetica", sans-serif; } ``` #### Result ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # unicode-range-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `unicode-range` | 1 | 12 | 36 | 15 | 3.1 | 18 | 36 | 14 | 3 | 1.0 | 4.4 | 3 | ## See also - [`font-display`](font-display) - [`font-family`](font-family) - [`font-stretch`](font-stretch) - [`font-style`](font-style) - [`font-weight`](font-weight) - [`font-feature-settings`](../../properties/font-feature-settings) - [`font-variation-settings`](font-variation-settings) - [`src`](src) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/unicode-range) --- ## Section: at-rules/@font-feature-values # `@font-feature-values` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since March 2023. The **`@font-feature-values`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) lets you use a common name in the [`font-variant-alternates`](../properties/font-variant-alternates) property for features activated differently in OpenType. This can help simplify your CSS when using multiple fonts. The `@font-feature-values` at-rule may be used either at the top level of your CSS or inside any CSS conditional-group at-rule. ## Syntax ``` @font-feature-values Font Name { font-display: swap; @styleset { nice-style: 12; } @swash { fancy: 2; } } ``` Each `@font-feature-values` block can contain a list of feature value blocks (listed below), as well as the [`font-display`](@font-feature-values/font-display) descriptor. ### Feature value blocks [`@swash`](#swash) Specifies a feature name that will work with the [`swash()`](../properties/font-variant-alternates#swash) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). A swash feature value definition allows only one value: `ident1: 2` is valid, but `ident2: 2 4` isn't. [`@annotation`](#annotation) Specifies a feature name that will work with the [`annotation()`](../properties/font-variant-alternates#annotation) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). An annotation feature value definition allows only one value: `ident1: 2` is valid, but `ident2: 2 4` isn't. [`@ornaments`](#ornaments) Specifies a feature name that will work with the [`ornaments()`](../properties/font-variant-alternates#ornaments) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). An ornaments feature value definition allows only one value: `ident1: 2` is valid, but `ident2: 2 4` isn't. [`@stylistic`](#stylistic) Specifies a feature name that will work with the [`stylistic()`](../properties/font-variant-alternates#stylistic) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). A stylistic feature value definition allows only one value: `ident1: 2` is valid, but `ident2: 2 4` isn't. [`@styleset`](#styleset) Specifies a feature name that will work with the [`styleset()`](../properties/font-variant-alternates#styleset) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). A styleset feature value definition allows an unlimited number of values: `ident1: 2 4 12 1` maps to the OpenType values `ss02`, `ss04`, `ss12`, and `ss01`. Note that values higher than `99` are valid, but don't map to any OpenType values and are ignored. [`@character-variant`](#character-variant) Specifies a feature name that will work with the [`character-variant()`](../properties/font-variant-alternates#character-variant) functional notation of [`font-variant-alternates`](../properties/font-variant-alternates). A character-variant feature value definition allows either one or two values: `ident1: 3` maps to `cv03=1`, and `ident2: 2 4` maps to `cv02=4`, but `ident2: 2 4 5` is invalid. ## Formal syntax ## Examples ### Using @styleset in a @font-feature-values rule ``` /* At-rule for "nice-style" in Font One */ @font-feature-values Font One { @styleset { nice-style: 12; } } /* At-rule for "nice-style" in Font Two */ @font-feature-values Font Two { @styleset { nice-style: 4; } } /* Apply the at-rules with a single declaration */ .nice-look { font-variant-alternates: styleset(nice-style); } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-feature-values | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-feature-values` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `annotation` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `character-variant` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `historical-forms` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `ornaments` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `styleset` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `stylistic` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | | `swash` | 111 | 111 | 34 | 97 | 9.1 | 111 | 34 | 75 | 9.3 | 22.0 | 111 | 9.3 | ## See also - The [`font-variant-alternates`](../properties/font-variant-alternates) property that uses values that this at-rule defines. © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-feature-values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-feature-values) --- ## Section: at-rules/@font-feature-values/font-display # `font-display` CSS at-rule descriptor The **`font-display`** descriptor for the [`@font-feature-values`](../@font-feature-values) at-rule sets the default value of how a font face is displayed based on whether and when it is downloaded. Setting a value for the `font-display` descriptor within a `@font-feature-values` block sets the default value of the `font-display` descriptor for the [`@font-face`](../@font-face) at-rule for all the fonts with the same [`font-family`](../@font-face/font-family) value. ## Syntax ``` /* Keyword values */ font-display: auto; font-display: block; font-display: swap; font-display: fallback; font-display: optional; ``` ### Values [`auto`](#auto) The font display strategy is defined by the user agent. [`block`](#block) Gives the font face a short block period, generally around 3 seconds, and an infinite swap period. [`swap`](#swap) Gives the font face an extremely small block period and an infinite swap period. [`fallback`](#fallback) Gives the font face an extremely small block period and a short swap period. [`optional`](#optional) Gives the font face an extremely small block period and no swap period. ## Description The `font-display` descriptor for `@font-feature-values` determines the font display timeline; it does so by setting a default `font-display` value for `@font-face` for the same `font-family` name. When `font-display` is omitted in `@font-face`, the user agent first looks for the `font-display` value that has been set via `@font-feature-values` for the relevant font-family. If no value is found, the user agent uses the `auto` value for `font-display`, in which case, the user agent determines the font display strategy. The font display timeline is based on a timer that starts when the user agent attempts to use a specific downloaded font face. The timeline is divided into three periods, as listed below. These periods dictate the rendering behavior of any element that uses the font face. - Font **block** period: If the font face is not loaded, elements attempting to use the font are rendered with an *invisible* fallback font face. The browser blocks visible text rendering, saving a space for the to-be-displayed text based on metrics of the fallback font. During the block period, text is not visible. At the end of the block period, if the font has not loaded, the text is rendered in the fallback font. - Font **swap** period: The swap period occurs after the block period (if there is one) and if the font face has not yet been loaded successfully. Elements attempting to use the not-yet-loaded font are rendered using the next available fallback font face. The formerly invisible fallback font face is painted onto the screen. If the font loads successfully during the swap period, the text that was rendered in the fallback font is updated — or swapped — with the newly loaded font. This step triggers a repaint. - Font **failure** period: If the font face has not loaded by the time the swap period expires or by the time the block period expires (if there is no swap period, as is the case with `optional`), the user agent treats the font as a failed load. As a result, the content becomes visible in the fallback font. The `font-display` descriptor allows you to set a default display policy for all `@font-face` rules, including those not under author control, such as third-party `@font-face` rules. When the `font-display` value is set via `@font-feature-values`, it becomes the default `font-display` value, and is applied to the entire font-family. However, any `font-display` value defined within individual `@font-face` blocks will override this default, but only for those blocks where the descriptor is defined. ## Examples ``` @font-feature-values "Leitura" { font-display: swap; @swash { fancy: 1; } } ``` The `font-display` descriptor in this example sets the default `font-display` value for the "Leitura" font to `swap` for all the `@font-face` blocks. Now there might be several `@font-face` blocks importing multiple font files for a single font-family. If one of those `@font-face` blocks includes a `font-display` descriptor, the specified value will be used for that specific font file only. All other blocks not including a `font-display` descriptor will default to `swap` instead of the user-agent's standard default `auto`. ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # descdef-font-feature-values-font-display | ## Browser compatibility Currently, no browsers support this feature. ## See also - [`font-display`](../@font-face/font-display) descriptor for [`@font-face`](../@font-face) at-rule - [CSS fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Fonts) module © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-feature-values/font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-feature-values/font-display) --- ## Section: at-rules/@font-palette-values # `@font-palette-values` CSS at-rule Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since November 2022. The **`@font-palette-values`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Syntax/At-rules) allows you to customize the default values of [font-palette](../properties/font-palette) created by the font-maker. ## Syntax ``` @font-palette-values --identifier { font-family: "Bixa"; } .my-class { font-palette: --identifier; } ``` The [<dashed-ident>](../values/dashed-ident) is a user-defined identifier, that while it looks like a [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) behaves in a different way and is not wrapped in a [CSS var() function](../values/var). ### Descriptors [`base-palette`](@font-palette-values/base-palette) Specifies the name or index of the base-palette, created by the font-maker, to use. [`font-family`](@font-palette-values/font-family) Specifies the name of the font family that this palette can be applied to. A `font-family` name is required for the `@font-palette-values` rule to be valid. [`override-colors`](@font-palette-values/override-colors) Specifies the colors in the base palette to override. ## Formal syntax ## Examples ### Overriding colors in an existing palette This example shows how you can change some or all of the colors in a color font. #### HTML ``` default colors alternate colors ``` #### CSS ``` @import "https://fonts.googleapis.com/css2?family=Bungee+Spice"; p { font-family: "Bungee Spice", fantasy; font-size: 2rem; } @font-palette-values --Alternate { font-family: "Bungee Spice"; override-colors: 0 #00ffbb, 1 #007744; } .alternate { font-palette: --Alternate; } ``` #### Result When overriding colors of the normal or base-palette at index 0 you do not need to declare which base-palette to use. This should only be done when overriding a different base-palette. If you are overriding all the colors then there is also no need to specify the base-palette to use. ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # at-ruledef-font-palette-values | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-palette-values` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | | `base-palette` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | | `font-family` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | | `override-colors` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | ## See also - [`font-palette`](../properties/font-palette) property - [`font-family`](@font-palette-values/font-family) descriptor - [`base-palette`](@font-palette-values/base-palette) descriptor - [`override-colors`](@font-palette-values/override-colors) descriptor - [`CSSFontPaletteValuesRule`](https://developer.mozilla.org/en-US/docs/Web/API/CSSFontPaletteValuesRule) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values) --- ## Section: at-rules/@font-palette-values/base-palette # `base-palette` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since November 2022. The **`base-palette`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) [descriptor](https://developer.mozilla.org/en-US/docs/Glossary/CSS_Descriptor) is used to specify the name or index of a pre-defined palette to be used for creating a new palette. If the specified `base-palette` does not exist, then the palette defined at index 0 will be used. ## Syntax ``` @font-palette-values --one { base-palette: 1; } ``` The `base-palette` [descriptor](https://developer.mozilla.org/en-US/docs/Glossary/CSS_Descriptor) is specified using a zero-based index of the font-maker created palettes. ### Values [``](#<index>) Specifies the index of the pre-defined palette to use. ## Formal definition ## Formal syntax ## Examples ### Changing the default palette in a font Using the [Rocher Color Font](https://www.harbortype.com/fonts/rocher-color/), this example shows two instances of switching the default palette in the font to an alternate palette created by the font-maker. #### HTML ``` default base-palette base-palette at index 2 base-palette at index 5 ``` #### CSS ``` @font-face { font-family: "Rocher"; src: url("[path-to-font]/RocherColorGX.woff2") format("woff2"); } h2 { font-family: "Rocher", fantasy; } @font-palette-values --two { font-family: "Rocher"; base-palette: 2; } @font-palette-values --five { font-family: "Rocher"; base-palette: 5; } .two { font-palette: --two; } .five { font-palette: --five; } ``` #### Result ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # base-palette-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `base-palette` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | ## See also - [`@font-palette-values`](../@font-palette-values) - [`font-family`](font-family) descriptor - [`override-colors`](override-colors) descriptor - [`font-palette`](../../properties/font-palette) property - [`CSSFontPaletteValuesRule.basePalette`](https://developer.mozilla.org/en-US/docs/Web/API/CSSFontPaletteValuesRule/basePalette) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values/base-palette](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values/base-palette) --- ## Section: at-rules/@font-palette-values/font-family # `font-family` CSS at-rule descriptor Baseline Widely available This feature is well established and works across many devices and browser versions. It's been available across browsers since November 2022. The [@font-palette-values](../@font-palette-values) [descriptor](https://developer.mozilla.org/en-US/docs/Glossary/CSS_Descriptor) **`font-family`** is used to specify which font-family palette values are to be applied to. This need to match exactly the values used when setting the CSS [font-family](../../properties/font-family). ## Syntax ``` @font-palette-values --Dark-mode { font-family: "Bungee Spice"; /* other palette settings follow */ } ``` Other palette values that follow apply only to the specified font family. You can create [@font-palette-values](../@font-palette-values) for other font families by using the same [<dashed-ident>s](../../values/dashed-ident). This means that if you have multiple Color Fonts and can use the same identifier for each. ### Values [``](#<family-name>) Specifies the name of the [font-family](../../properties/font-family). ## Formal definition ## Formal syntax ## Examples ### Using matching family names In this example, when the `font-family` descriptor is used in the [@font-palette-values](../@font-palette-values) at-rule, the same value is used for the `font-family`, as when it is declared. #### HTML ``` This is spicy This is extra hot & spicy ``` #### CSS ``` @import "https://fonts.googleapis.com/css2?family=Bungee+Spice"; @font-palette-values --bungee-extra-spicy { font-family: "Bungee Spice"; override-colors: 0 darkred, 1 red; } h2 { font-family: "Bungee Spice", fantasy; } h2.extra-spicy { font-palette: --bungee-extra-spicy; } ``` #### Result ### Using the same palette identifier for multiple font-families In this example, two [@font-palette-values](../@font-palette-values) at-rules are set for two font families, but both the at-rules use the same dashed-ident identifier, `--Dark-Mode`. This helps to set the [font-palette](../../properties/font-palette) property for multiple elements, `h1` and `h2` in this case, at the same time. This can be useful when you want to update font colors to match your site's branding. ``` @font-palette-values --Dark-Mode { font-family: "Bungee Spice"; /* palette settings for Bungee Spice */ } @font-palette-values --Dark-Mode { font-family: "Bixa"; /* palette settings for Bixa */ } h1, h2 { font-palette: --Dark-Mode; } h1 { font-family: "Bungee Spice", fantasy; } h2 { font-family: "Bixa", fantasy; } ``` ## Specifications | Specification | | --- | | CSS Fonts Module Level 4 # font-family-2-desc | ## Browser compatibility | | Desktop | Mobile | | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on iOS | Samsung Internet | WebView Android | WebView on iOS | | `font-family` | 101 | 101 | 107 | 87 | 15.4 | 101 | 107 | 70 | 15.4 | 19.0 | 101 | 15.4 | ## See also - [`font-family`](../@font-face/font-family) - [`@font-palette-values`](../@font-palette-values) - [`override-colors`](override-colors) descriptor - [`font-palette`](../../properties/font-palette) property - [`CSSFontPaletteValuesRule.fontFamily`](https://developer.mozilla.org/en-US/docs/Web/API/CSSFontPaletteValuesRule/fontFamily) © 2005–2025 MDN contributors. Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later. [https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values/font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-palette-values/font-family) --- METRICS --- - Files Extracted: 2 - Estimated Token Budget: ~65646 tokens - Recency Window: Active (< 180 days) - Canonical Reference: https://codewiki.google/github.com/mdn/content