# Axis Registry Source: /docs/api/axis-registry # Axis Registry [#axis-registry] The Axis Registry endpoint gives detailed descriptions of variable axis tags and their corresponding values. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/axis-registry` ## Response [#response] The API response for the Fontlist endpoint is a JSON object. ### Attributes: [#attributes] Returns an object of: | Attribute | Type | Description | | --------- | --------------------------------- | --------------- | | \[tag] | Record\ | Axis tag object |
#### AxisRegistryItem: [#axisregistryitem] | Attribute | Type | Description | | ----------- | ------ | ------------------------------- | | name | string | Axis name | | description | string | Axis description | | min | number | Minimum value possible for axis | | max | number | Maximum value possible for axis | | default | number | Default value for axis | | precision | number | Precision | ### Response example: [#response-example] ```json { ... "ARRR":{ "name":"AR Retinal Resolution", "description":"Resolution-specific enhancements in AR/VR typefaces to optimize rendering across the different resolutions of the headsets making designs accessible and easy to read.", "min":10, "max":60, "default":10, "precision":0 }, ... } ``` --- # Font ID Source: /docs/api/font-id # Font ID [#font-id] The Font ID endpoint allows you to retrieve detailed information about a specific font supported by Fontsource. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/fonts/{id}` ## Response [#response] The API response for the Font ID endpoint is a JSON object that provides comprehensive details about the font. ### Attributes: [#attributes] Returns an object with: | Attribute | Type | Description | | ------------ | ----------------------- | -------------------- | | id | string | The font ID | | family | string | The font family | | subsets | string\[] | Language subsets | | weights | number\[] | Font weights | | styles | string\[] | Font styles | | unicodeRange | Record\ | Unicode range | | defSubset | string | Default subset | | variable | boolean | Is the font variable | | lastModified | string | Last modified date | | category | string | Font category | | version | string | Font version | | type | string | Font type | | variants | Record\ | File variants |
Variants is an object that creates records starting with `weight`, `style`, `subset` followed by a URL object containing each supported file format (`woff2`, `woff`, `ttf`). ### Response example: [#response-example] ```json { "id": "abel", "family": "Abel", "subsets": ["latin"], "weights": [400], "styles": ["normal"], "unicodeRange": { "latin": "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD" }, "defSubset": "latin", "variable": false, "lastModified": "2020-09-10", "category": "sans-serif", "version": "v12", "type": "google", "variants": { "400": { "normal": { "latin": { "url": { "woff2": "https://cdn.jsdelivr.net/fontsource/fonts/abel@latest/latin-400-normal.woff2", "woff": "https://cdn.jsdelivr.net/fontsource/fonts/abel@latest/latin-400-normal.woff", "ttf": "https://cdn.jsdelivr.net/fontsource/fonts/abel@latest/latin-400-normal.ttf" } } } } } } ``` ### Example: [#example] * `GET https://api.fontsource.org/v1/fonts/abel` * `GET https://api.fontsource.org/v1/fonts/open-sans` --- # Fontlist Source: /docs/api/fontlist # Fontlist [#fontlist] The Fontlist endpoint provides an object that contains a list of fonts and their associated properties. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/fontlist` * `GET https://api.fontsource.org/fontlist?{query}` ## Response [#response] The API response for the Fontlist endpoint is a JSON object that represents the available fonts and their corresponding types. ### Attributes [#attributes] Returns an object of: | Attribute | Type | Description | | --------- | ------------------------ | ------------- | | \[id] | string | The font ID | | type | google \| icons \| other | The font type | ### Response example [#response-example] ```json { ... "abeezee": "google", "material-icons": "icons", "yakuhanjp": "other" ... } ``` ## Queries [#queries] The Fontlist API supports the following queries without values: | Query | Returns ID Property | Property Type | | ------------ | ------------------- | ------------- | | family | Family names | string | | subsets | Supported subsets | string\[] | | weights | Supported weights | number\[] | | styles | Supported styles | string\[] | | variable | If font is variable | boolean | | category | Font category | string | | lastModified | Last modified date | string | | version | Font version | string | | type | Font type | string | ### Example [#example] * `GET https://api.fontsource.org/fontlist?family` * `GET https://api.fontsource.org/fontlist?subsets` * `GET https://api.fontsource.org/fontlist?lastModified` > **Note:** You cannot query for multiple properties at once. --- # Fonts Source: /docs/api/fonts # Fonts [#fonts] The Fonts endpoint provides an array of individual font objects. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/fonts` * `GET https://api.fontsource.org/v1/fonts?{query}` ## Response [#response] The API response for the Fonts endpoint is an array of font objects. Each font object represents a specific font and provides detailed information about it. ### Attributes [#attributes] Returns an array of: | Attribute | Type | Description | | ------------ | --------- | -------------------- | | id | string | The font ID | | family | string | The font family | | subsets | string\[] | Language subsets | | weights | number\[] | Font weights | | styles | string\[] | Font styles | | defSubset | string | Default subset | | variable | boolean | Is the font variable | | lastModified | string | Last modified date | | category | string | Font category | | version | string | Font version | | type | string | Font type | ### Response example [#response-example] ```json [ { "id": "abeezee", "family": "ABeeZee", "subsets": ["latin"], "weights": [400], "styles": ["italic", "normal"], "defSubset": "latin", "variable": false, "lastModified": "2020-09-02", "category": "sans-serif", "version": "v14", "type": "google" } ... ] ``` ## Queries [#queries] The Fonts endpoint allows you to send queries to filter the list of fonts. Multiple queries can be combined using the & operator. Attributes in arrays can be separated using a comma separator `,` which acts as an AND operator.
You can include additional queries in the URL to filter the responses based on specific criteria. For example, [`api.fontsource.org/v1/fonts?subsets=latin,latin-ext&variable=true`](https://api.fontsource.org/v1/fonts?subsets=latin,latin-ext\&variable=true) will return fonts that match subsets `latin` and `latin-ext`, as well as if it is a variable font. ### Options [#options] You can use the following queries to filter the list of fonts: | Query | Type | Example | | ------------ | --------- | ----------------------- | | id | string | id=roboto | | family | string | family=Roboto | | subsets | string | subsets=latin,latin-ext | | weights | number\[] | weights=100,900 | | styles | string\[] | styles=normal,italic | | defSubset | string | defSubset=arabic | | variable | boolean | variable=true | | lastModified | string | lastModified=2020-09-02 | | category | string | category=display | | version | string | version=v14 | | type | string | type=google | ### Example [#example] * `GET https://api.fontsource.org/v1/fonts?subsets=latin,latin-ext&variable=true` * `GET https://api.fontsource.org/v1/fonts?weights=400,900&styles=normal` * `GET https://api.fontsource.org/v1/fonts?lastModified=2022-09-22` --- # Getting Started API Source: /docs/api/introduction # Introduction [#introduction] The Fontsource API provides developers with access to information about the fonts supported by the Fontsource repository. > **Note:** Please [sponsor](https://github.com/sponsors/ayuhito) the project if you use the API to support its development! ## Usage [#usage] The Fontsource API is a read-only API that can be accessed by any HTTP client. An example URL that accepts a GET request is [`api.fontsource.org/v1/fonts`](https://api.fontsource.org/v1/fonts). ## Errors [#errors] | Code | Description | | ---- | ------------------------------------ | | 200 | The request was successful | | 400 | The request was malformed | | 404 | The requested resource was not found | | 422 | The request was unprocessable | | 429 | The request was rate limited | | 500 | An internal server error occurred | ## Limits [#limits] * We reserve the right to add more properties to objects, but will never change or remove them. * While the intention is not to throttle the API, we reserve the right to do so if necessary under fair use. The current hard limit is 2500 requests per 10 seconds but constant usage at this rate can result in a temporary ban. --- # Stats Source: /docs/api/stats # Stats [#stats] The Stats endpoint provides download statistics for each font. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/stats/{id}` ## Response [#response] The API response for the Stats endpoint is a JSON object that provides download statistics for each font. ### Attributes [#attributes] Returns an object with: | Attribute | Type | Description | | --------- | ------------------------ | ------------------------ | | total | DownloadStats | Total download counts | | static | DownloadStats | Static download counts | | variable | Optional\ | Variable download counts |
#### DownloadStats [#downloadstats] | Attribute | Type | Description | | ------------------- | ------ | -------------------------- | | npmDownloadTotal | number | Total NPM download count | | npmDownloadMonthly | number | Monthly NPM download count | | jsDelivrHitsTotal | number | Total jsDelivr hits | | jsDelivrHitsMonthly | number | Monthly jsDelivr hits | ### Response example [#response-example] ```json { "total":{ "npmDownloadTotal":8566215, "npmDownloadMonthly":731202, "jsDelivrHitsTotal":46488758, "jsDelivrHitsMonthly":8210654 }, "static":{ "npmDownloadTotal":8288204, "npmDownloadMonthly":637495, "jsDelivrHitsTotal":46483427, "jsDelivrHitsMonthly":8207141 }, "variable":{ "npmDownloadTotal":278011, "npmDownloadMonthly":93707, "jsDelivrHitsTotal":5331, "jsDelivrHitsMonthly":3513 } } ``` ### Example [#example] * `GET https://api.fontsource.org/v1/stats/abel` * `GET https://api.fontsource.org/v1/stats/open-sans` ## Aggregate badges [#aggregate-badges] Shields-compatible badges are available for totals across all active font packages: * `GET https://api.fontsource.org/v1/stats/badge/npm-monthly` * `GET https://api.fontsource.org/v1/stats/badge/npm-total` * `GET https://api.fontsource.org/v1/stats/badge/jsdelivr-monthly` * `GET https://api.fontsource.org/v1/stats/badge/jsdelivr-total` --- # Variable Source: /docs/api/variable # Variable [#variable] The Variable endpoint allows you get specific axis data for a variable font. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/variable/{id}` ## Response [#response] The API response for the Variable endpoint is a JSON object that provides axis data for a variable font. ### Attributes [#attributes] Returns an object with: | Attribute | Type | Description | | --------- | ------------------------- | ----------- | | family | string | Font family | | axes | Record\ | Axis data |
#### AxesData [#axesdata] | Attribute | Type | Description | | --------- | ------ | ------------- | | default | number | Default value | | min | number | Minimum value | | max | number | Maximum value | | step | number | Step value | ### Response example [#response-example] ```json { "axes": { "slnt": { "default": "0", "min": "-10", "max": "0", "step": "1" }, "wght": { "default": "400", "min": "100", "max": "900", "step": "1" } }, "family": "Inter" } ``` ### Example [#example] * `GET https://api.fontsource.org/v1/variable/inter` * `GET https://api.fontsource.org/v1/variable/roboto-flex` * `GET https://api.fontsource.org/v1/variable/wavefont` --- # Version Source: /docs/api/version # Version [#version] The Version endpoint provides NPM version information for each package. ## HTTP Request [#http-request] * `GET https://api.fontsource.org/v1/version/{id}` ## Response [#response] The API response for the Version endpoint is a JSON object that provides NPM version information for each package. ### Attributes [#attributes] Returns an object with: | Attribute | Type | Description | | -------------- | -------------------- | --------------------------------------------- | | latest | string | Latest static NPM version | | static | string\[] | Static NPM versions sorted newest to oldest | | latestVariable | Optional\ | Latest variable NPM version | | variable | Optional\ | Variable NPM versions sorted newest to oldest | ### Response example [#response-example] ```json { "latest": "5.0.4", "static": [ "5.0.4", "5.0.3", "5.0.2", "5.0.1", "5.0.0", "4.2.2", "4.2.1", "4.2.0", "4.1.1", "4.1.0", "4.0.1", "4.0.0" ], "latestVariable": "5.0.7", "variable": [ "5.0.7", "5.0.6", "5.0.5", "5.0.4", "5.0.3", "5.0.2", "5.0.1", "5.0.0" ] } ``` ### Example [#example] * `GET https://api.fontsource.org/v1/version/abel` * `GET https://api.fontsource.org/v1/version/open-sans` --- # AI and LLMs Source: /docs/getting-started/ai-and-llms # AI and LLMs [#ai-and-llms] Fontsource publishes AI-readable documentation so coding assistants can reference the current docs without crawling HTML pages. These routes are useful when working with tools such as Cursor, Windsurf, GitHub Copilot, ChatGPT, Claude, or local agent workflows. ## Available Files [#available-files] ### `/llms.txt` [#llmstxt] Use [`/llms.txt`](/llms.txt) as the primary entry point for AI tools. It is a compact index of the Fontsource documentation and links to the relevant docs pages. ### `/llms-full.txt` [#llms-fulltxt] Use [`/llms-full.txt`](/llms-full.txt) when a tool needs the full documentation content in one Markdown file. This file is larger, so `/llms.txt` is usually the better first choice for agents with limited context. ### Page Markdown [#page-markdown] Every documentation page is also available as Markdown by adding `.md` to the page URL. For example, this page is available at [`/docs/getting-started/ai-and-llms.md`](/docs/getting-started/ai-and-llms.md). Use page-level Markdown when an AI tool only needs one focused topic, such as installation, variable fonts, or a framework guide. ## What’s Included [#whats-included] The AI-readable docs include the human-maintained documentation pages, guides, and API reference pages. Generated font catalogue pages are intentionally excluded so the export stays focused on how to use Fontsource rather than listing every available font package. ## Usage Examples [#usage-examples] ### Cursor [#cursor] Add `https://fontsource.org/llms.txt` with Cursor’s docs feature, then ask questions against the indexed Fontsource docs. Example prompt: ```txt Using Fontsource, show me the recommended way to install and import IBM Plex Sans in a Vite app. Use https://fontsource.org/llms.txt as the documentation source. ``` ### ChatGPT, Claude, and Agent Workflows [#chatgpt-claude-and-agent-workflows] Ask the assistant to read `/llms.txt` first, then fetch the specific Markdown page it needs. Example prompt: ```txt Read https://fontsource.org/llms.txt, then use the most relevant Fontsource Markdown docs page to explain how variable fonts should be imported. ``` ### Limited Context Tools [#limited-context-tools] For tools with small context windows, prefer a focused page-level Markdown URL instead of `/llms-full.txt`. Example: ```txt Use https://fontsource.org/docs/getting-started/install.md to answer this question about installing Fontsource packages. ``` ## Update Cadence [#update-cadence] These files are generated from the docs source during the website build, so they stay aligned with the documentation shipped on the website. --- # CDN Source: /docs/getting-started/cdn # CDN [#cdn] Fontsource has partnered with [jsDelivr](https://www.jsdelivr.com/) for a custom proxy for its stylesheets and font files, allowing for niche use cases where a stable asset link is required. All files are versioned according to [Semver](https://semver.org/). > **Note:** We recommend self-hosting your fonts if possible, but we understand there are suitable use cases for a CDN. ## Usage [#usage] To use the Fontsource CDN, open **Developer setup** on a font’s **Get font** page and choose **CDN**. For example, [Roboto Flex](/fonts/roboto-flex/use?tab=web\&method=cdn) generates the relevant URLs and CSS for your project. ## URL Formats [#url-formats] The Fontsource CDN serves generated CSS stylesheets and direct font files. ### Choosing a Version [#choosing-a-version] Use an exact version such as `@5.2.7` in production. Exact versions are immutable and receive long-lived caching, making deployments reproducible without query-string cache busters. Update the version in the URL when you want to upgrade the font. Floating versions such as `@latest`, `@5`, or `@5.2` automatically resolve to a matching release. They use shorter caches and may not update immediately, so use them only when automatic upgrades are intentional. A floating stylesheet still contains exact-version font file URLs, keeping all files in that stylesheet on the same release. ### CSS Stylesheets [#css-stylesheets] Generated stylesheets include the matching `@font-face` declarations and font file URLs. Use `.min.css` instead of `.css` when you want the minified version. * Static: `https://cdn.jsdelivr.net/fontsource/css/{id}@{version}/{file}.css` * Variable: `https://cdn.jsdelivr.net/fontsource/css/{id}:vf@{version}/{file}.css` For example, load the default Open Sans stylesheet: ```html ``` Load only the minified Latin subset: ```html ``` Variable font stylesheets use the same `.min.css` suffix: ```html ``` ### Static Font URLs [#static-font-urls] Static font URLs follow this pattern: * `https://cdn.jsdelivr.net/fontsource/fonts/{id}@{version}/{subset}-{weight}-{style}.{extension}` ### Variable Font URLs [#variable-font-urls] Variable fonts URLs have the format: * `https://cdn.jsdelivr.net/fontsource/fonts/{id}:vf@{version}/{subset}-{axes}-{style}.woff2` ## Example URLs [#example-urls] Here are some example URLs that demonstrate how to use Fontsource’s CDN with different fonts and configurations: * Floating variable URL for the latest version of Roboto Flex with Latin subset, wght axis, and normal style: `https://cdn.jsdelivr.net/fontsource/fonts/roboto-flex:vf@latest/latin-wght-normal.woff2` * Variable URL for Roboto Flex version 5.0.8 with Cyrillic Extended subset, normal weight, and normal style: `https://cdn.jsdelivr.net/fontsource/fonts/roboto-flex:vf@5.0.8/cyrillic-ext-wdth-normal.woff2` * Static URL for Inter version 5.0 with Vietnamese subset, 500 weight, and normal style: `https://cdn.jsdelivr.net/fontsource/fonts/inter@5.0/vietnamese-500-normal.woff2` * Static URL for Inter version 5 with Greek Extended subset, 400 weight, and italic style: `https://cdn.jsdelivr.net/fontsource/fonts/inter@5/greek-ext-400-italic.woff2` --- # Font Display Source: /docs/getting-started/display # Font Display [#font-display] Font display is a CSS property that controls how fonts appear on your website. By default, Fontsource uses the `swap` value for the `font-display` property. This means that while a custom font is loading, the browser displays a fallback font. Once the custom font is ready, the browser swaps it in place of the fallback font. > **Note:** You can learn more about the `font-display` property in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display). To customise the `font-display` property for a specific font, open **Custom CSS** under **[Get font](https://fontsource.org/fonts/open-sans/use?tab=web\&setup=custom)** to generate `@font-face` rules with your preferred value. ## Example [#example] To set the `font-display` property to `optional` for Open Sans, you can create the following `@font-face` rule: ```css @font-face { font-family: 'Open Sans Variable'; font-style: normal; font-display: optional; font-weight: 300 800; src: url(@fontsource-variable/open-sans/files/open-sans-latin-wght-normal.woff2) format('woff2-variations'); unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD; } ``` > **Note:** This method is only compatible with **Vite-based** frameworks or similar setups that support CSS bundling with `url()` rewrites. You can then include this rule in your global CSS file and apply it to your components using the following CSS: ```css body { font-family: 'Open Sans Variable', sans-serif; } ``` --- # Faces Mixin Source: /docs/getting-started/faces-mixin # Faces Mixin [#faces-mixin] The font faces mixin allows you to generate a highly customizable CSS file for your font by modifying various [`@font-face`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) variables. This guide explains how to use the Faces mixin in your Sass/SCSS projects. ## Installation [#installation] To use the Faces mixin, you must install the `@fontsource-utils/scss` helper package and the specific font package you want to customize: ```sh npm install @fontsource-utils/scss yarn add @fontsource-utils/scss pnpm add @fontsource-utils/scss bun add @fontsource-utils/scss ``` Then, import the Fontsource mixins in your Sass/SCSS file using the `@use` rule: ```scss @use "pkg:@fontsource-utils/scss" as fontsource; @use "pkg:@fontsource-variable/recursive/scss" as recursive; ``` ## Usage [#usage] Once you have imported the mixin, you can use it to generate a CSS file with customized font variations. Here’s an example that generates a CSS file similar to `recursive/latin-500-italic.css`: ```scss @include fontsource.faces( $metadata: recursive.$metadata, $subsets: latin, $weights: 500, $styles: italic ); ``` You can customize the font variations by specifying different subsets, weights, and styles. Use the all option if you want to include all available options for a specific property. Here’s an example that includes multiple subsets, weights, and all available styles: ```scss @include fontsource.faces( $metadata: recursive.$metadata, $subsets: ( latin, greek, ), $weights: ( 300, 400, 800, ), $styles: all ); ``` ### Mixin Arguments [#mixin-arguments] The Faces mixin accepts several properties as arguments, allowing you to customize various aspects of the font. Here are the available arguments:: | Variable | Description | Options | Default | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | | $family | Font family name (see [font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family)) | Any string | Metadata default used (e.g. “Open Sans”) | | $display | How the font is displayed when loading (see [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display)) | One of: `auto`, `block`, `swap`, `fallback`, `optional` | `swap` | | $formats | List of included font file formats (see [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src)) | `all`, or any of: `woff`, `woff2` | `all` | | $subsets | List of included subsets | `all`, or any of the subsets listed for the font | Metadata default used (e.g. latin) | | $weights | List of included weights (see [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight)) | `all`, or any of the weights listed for the font | Metadata default used (e.g. 400) | | $styles | List of included styles (see [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style)) | `all`, or any of the styles listed for the font (usually `normal` and `italic`) | Metadata default used (e.g. normal) | | $axes | List of included variable font axes (see [Variable fonts guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide)) | `all` (which uses `full`), or any of the axes listed for the font | `full` | The following advanced properties shouldn’t need to be modified as often, but are still available for use: | Variable | Description | Default | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | $metadata | [Metadata map](https://github.com/fontsource/font-files/blob/main/fonts/google/open-sans/scss/metadata.scss), which is used for resolving default options, available properties, and source paths | Default package metadata (located in `scss/metadata.scss`) | | $directory | Base directory used for the font source paths | Default package path (e.g. `~@fontsource/open-sans/files`) | ### Global Configuration [#global-configuration] The arguments for the Faces mixin can also be set directly on module import, which will set the new defaults throughout different uses of the mixin. Here’s an example: ```scss @use "@fontsource-utils/scss" as fontsource with ( $weights: ( 300, 700, ), $family: "Fontsource Custom" ); @include fontsource.faces( $metadata: recursive.$metadata // The global configuration can still be overwritten through arguments $family: "Recursive Other" ); ``` By setting the arguments on module import, you can easily configure the defaults for the Faces mixin. --- # FAQ Source: /docs/getting-started/faq # Frequently Asked Questions [#frequently-asked-questions] This page addresses common issues and questions that users encounter when working with Fontsource. ## TypeScript Errors [#typescript-errors] ### Cannot find module ‘@fontsource/\[font-name]’ or its corresponding type declarations [#cannot-find-module-fontsourcefont-name-or-its-corresponding-type-declarations] If you’re encountering TypeScript errors like: ```sh Cannot find module '@fontsource/inter' or its corresponding type declarations. Cannot find module '@fontsource-variable/open-sans' or its corresponding type declarations. ``` This is due to TypeScript’s [`noUncheckedSideEffects`](https://www.typescriptlang.org/tsconfig/#noUncheckedSideEffectImports) flag rejecting CSS files as having side effects. To resolve this, add ambient module declarations to your project: Create a global TypeScript declaration file (e.g., `src/globals.d.ts`) and include: ```ts // ./src/globals.d.ts declare module "*.css"; declare module "@fontsource/*" {} declare module "@fontsource-variable/*" {} ``` This tells TypeScript to allow imports from CSS files and Fontsource packages without type checking. ## Performance Issues [#performance-issues] ### Large bundle sizes [#large-bundle-sizes] If your bundle size is larger than expected: * **Use variable fonts**: When available, variable fonts can significantly reduce bundle size compared to importing multiple static weights. ```jsx // Instead of multiple static weights import "@fontsource/open-sans/300.css"; import "@fontsource/open-sans/400.css"; import "@fontsource/open-sans/500.css"; import "@fontsource/open-sans/700.css"; // Use variable fonts import "@fontsource-variable/open-sans"; ``` * **Import only needed weights**: Only import the specific weights and styles you actually use. ```jsx import "@fontsource/open-sans/400.css"; // Only import weight 400 import "@fontsource/open-sans/700.css"; // Only import weight 700 ``` ## Variable Fonts [#variable-fonts] ### Variable font not working [#variable-font-not-working] If variable fonts aren’t working as expected: * **Check browser support**: Ensure the target browsers support variable fonts. * **Verify font-family name**: Variable fonts typically have “Variable” in their font-family name: ```css body { font-family: "Open Sans Variable", sans-serif; } ``` * **Use CSS custom properties**: For variable fonts, you can use CSS custom properties or `font-variation-settings`: ```css .heading { font-family: "Open Sans Variable", sans-serif; font-weight: 600; /* Or use variation settings directly */ font-variation-settings: "wght" 600; } ``` --- # Generator Mixin Source: /docs/getting-started/generator-mixin # Generator Mixin [#generator-mixin] The generator mixin in Fontsource is a powerful tool that allows for advanced use cases in Sass. It provides a way to dynamically generate CSS based on the specified properties. Please note that the generator mixin is more advanced and is recommended for users who require fine-grained control over their font styles. For most use cases, the [Faces mixin](./faces-mixin) is sufficient. ## Installation [#installation] To use the Generator mixin, you must install the `@fontsource-utils/scss` helper package and the specific font package you want to customize: ```sh npm install @fontsource-utils/scss yarn add @fontsource-utils/scss pnpm add @fontsource-utils/scss bun add @fontsource-utils/scss ``` Then, import the Fontsource mixins along with the `sass:map` module to extract the generator properties. Here’s an example of how to import the generator mixin for the Open Sans font: ```scss @use "sass:map"; @use "pkg:@fontsource-utils/scss" as fontsource; ``` ## Usage [#usage] The generator mixin allows you to generate CSS based on the provided properties. It uses a loop to iterate over the properties and generate CSS from the content block. Here’s an example of using the generator mixin: ```scss @include fontsource.generator( $weights: ( 400, 800, ) ) using ($props) { /* CSS generated dynamically based on the properties */ @font-face { font-family: "Random stuff #{map.get($props, font-family)}"; font-style: normal; font-weight: map.get($props, font-weight); src: map.get($props, src); } } ``` In this example, the `fontsource.generator` mixin is called with the desired properties, and the content block is used to generate CSS dynamically based on those properties. ### Arguments [#arguments] The generator mixin accepts the same arguments as the faces mixin. You can refer to the [arguments section](./faces-mixin#arguments) of the faces mixin documentation for a complete list of available arguments. ### Properties [#properties] The generator mixin provides several properties that can be accessed within the content block. These properties are passed into the content block and can be used to generate dynamic CSS. Here are the properties available: #### Mixin Arguments [#mixin-arguments] All the arguments passed into the generator mixin are resolved to their final values and passed into the content block. These values are constant throughout each content block iteration. You can refer to the [arguments section](./faces-mixin#arguments) of the faces mixin documentation for a complete list of available arguments. ```scss @include generator( $weights: ( 400, 800, ) ) using ($props) { /* #{map.get($props, weights)} will resolve to: Hello 400, 800 */ /* #{map.get($props, family)} will default to: Open Sans */ } ``` | Property | Example | | --------- | -------------------------------------------------------------------------------------------------------- | | metadata | [see here](https://github.com/fontsource/font-files/blob/main/fonts/google/open-sans/scss/metadata.scss) | | directory | `@fontsource/open-sans/files` | | family | Open Sans | | display | `swap` | | formats | `(woff, woff2)` | | subsets | `(latin)` | | weights | `(400, 800)` | | styles | `(normal)` | | axes | `(wght, ital)` | #### Loop Parameters [#loop-parameters] These variables change on each iteration of the content block: | Property | Example | | ------------- | ----------------------------------------------------- | | variant | `open-sans-latin-800-italic` | | unicodeSubset | `cyrillic` | | unicodeRange | `(U+0301,U+0400-045F,U+0490-0491,U+04B0-04B1,U+2116)` | | weight | `800` | | axis | `wght` | | style | `italic` | #### CSS Properties [#css-properties] These are the CSS properties that are calculated and used by default in the faces mixin: | Property | Example | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | font-family | `"Open Sans"` | | font-style | `italic` | | font-display | `swap` | | font-weight | `800` | | font-stretch | `300 800` | | src | `url(./files/open-sans-cyrillic-800-italic.woff2) format('woff2'), url(./files/open-sans-cyrillic-800-italic.woff) format('woff')` | | unicode-range | `U+0301,U+0400-045F,U+0490-0491,U+04B0-04B1,U+2116` | ## Example [#example] Here’s an example of how the faces mixin uses the generator mixin for its implementation: ```scss @include generator( // Faces mixin arguments are passed down to the generator $metadata: $metadata, $directory: $directory, $family: $family, $display: $display, $formats: $formats, $subsets: $subsets, $weights: $weights, $styles: $styles, $axes: $axes ) using ($props) { /* #{map.get($props, variant)} */ @font-face { font-family: map.get($props, font-family); font-style: map.get($props, font-style); font-display: map.get($props, font-display); font-weight: map.get($props, font-weight); font-stretch: map.get($props, font-stretch); unicode-range: map.get($props, unicode-range); src: map.get($props, src); } } ``` In this example, the faces mixin passes its arguments to the generator mixin, and the content block generates CSS based on the properties. --- # Install Source: /docs/getting-started/install # Install [#install] Fontsource packages let you bundle and self-host fonts with your web application. When a family supports variable fonts, start with its variable package. It provides a continuous range of weights and often needs fewer files than several static faces. ## Prerequisites [#prerequisites] Before proceeding with the installation, ensure that you are using a bundler, such as Vite or Webpack, to handle importing CSS into your final bundle. Please refer to the [Fontsource Guides](/docs/guides) section to see detailed instructions for your preferred framework. If a family does not provide a variable package, use its static package instead. ## Setup [#setup] To install a font from Fontsource, follow the steps below. ### 1. Choose a Package [#1-choose-a-package] Select the font package you wish to install. Each font package corresponds to a specific font. ### 2. Install the Package [#2-install-the-package] Use your preferred package manager to install the variable package. For example, to install Open Sans, run: ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` > **Note:** Alternatively, you can download the font files yourself in each directory listing. ### 3. Import the Font [#3-import-the-font] In your application’s entry file, page, or site component, import the font package. The import method determines which font files are included. #### Recommended Import [#recommended-import] Import the package once in your application’s entry file. The default variable face usually includes the full weight range in the normal style. ```jsx import "@fontsource-variable/open-sans"; ``` The generated CSS uses `unicode-range`, so the browser downloads only the character sets used on the page. You normally do not need to choose subsets manually. See [Subsets](/docs/getting-started/subsets) for the uncommon cases that need explicit subset imports. To use italic or additional variable axes, see the [Variable Fonts](/docs/getting-started/variable) guide. #### Static Fonts [#static-fonts] Use the static package when a family has no variable font or when your project specifically needs fixed font faces. ```sh npm install @fontsource/open-sans yarn add @fontsource/open-sans pnpm add @fontsource/open-sans bun add @fontsource/open-sans ``` Import only the weights and styles the project uses. Each import adds one fixed face. The root import provides the default weight, which is **400** for most families: ```jsx import "@fontsource/open-sans"; ``` Specific weights and styles use their own imports: ```jsx import "@fontsource/open-sans/300.css"; import "@fontsource/open-sans/900-italic.css"; ``` If you need both a regular and an italic style for the same weight, you’ll need two separate imports. The import for a normal style **does not** include its italic variant. ```jsx import "@fontsource/open-sans/900.css"; // Includes weight 900. import "@fontsource/open-sans/900-italic.css"; // Includes weight 900 in italic style. ``` If you need many weights, prefer the variable package instead of adding every static face. > **Note:** Each font package will provide information on the supported weights and styles in the directory listing or package README. ### 4. TypeScript Configuration [#4-typescript-configuration] If you’re using TypeScript, you may encounter errors when importing CSS files due to TypeScript’s [`noUncheckedSideEffects`](https://www.typescriptlang.org/tsconfig/#noUncheckedSideEffectImports) flag. To resolve this, add ambient module declarations to your project. Create a global TypeScript declaration file (e.g., `src/globals.d.ts`) and include the following: ```ts // ./src/globals.d.ts declare module "*.css"; declare module "@fontsource/*" {} declare module "@fontsource-variable/*" {} ``` This tells TypeScript to allow imports from CSS files and Fontsource packages without type checking. > **Note:** If you’re using a bundler like **Vite** or a framework that handles CSS imports automatically, you likely won’t need to do this. ### 5. CSS [#5-css] Once the font is imported, you can reference it in your CSS stylesheets, CSS Modules, or CSS-in-JS using the font family name. ```css body { font-family: "Open Sans", sans-serif; } ``` That’s it! You have successfully installed and imported a font from Fontsource into your web application. --- # Introduction Source: /docs/getting-started/introduction # Introduction [#introduction] Fontsource is a collection of open-source fonts that are packaged into individual NPM packages for self-hosting in your web applications. This documentation outlines the benefits of using Fontsource and how to get started. ## Advantages [#advantages] ### 1. Performance [#1-performance] * Self-hosting fonts can **significantly improve website performance** by eliminating the extra latency caused by additional DNS resolution and TCP connection establishment that is required when using a CDN like Google Fonts. This can help to prevent doubled visual load times for simple websites, as benchmarked [here](https://github.com/HTTPArchive/almanac.httparchive.org/pull/607) and [here](https://github.com/reactiflux/reactiflux.com/pull/21). ### 2. Version Locking [#2-version-locking] * Fonts remain **version locked**. Google often pushes updates to their fonts [without notice](https://github.com/google/fonts/issues/1307), which may interfere with your live production projects. Manage your fonts like any other NPM dependency. ### 3. Privacy [#3-privacy] * Commit to **privacy**. Google does track the usage of their fonts and for those who are extremely privacy concerned, self-hosting is an alternative. ### 4. Offline [#4-offline] * Your **fonts load offline**. This feature is beneficial for Progressive Web Apps and situations where you have limited or no access to the internet. ### 5. Additional Fonts [#5-additional-fonts] * **Support for fonts outside the Google Font ecosystem**. This repository is constantly evolving with [other Open Source fonts](https://github.com/fontsource/font-files). Feel free to contribute! --- # Material Icons Source: /docs/getting-started/material-icons # Material Icons [#material-icons] Fontsource provides support for all variations of Material Icons. You can find more details on how to use the font variation of the project [here](https://google.github.io/material-design-icons/#icon-font-for-the-web). ## Installation [#installation] To install Material Icons from Fontsource, follow the steps below: ### 1. Install Icon Set [#1-install-icon-set] Install the desired icon set from Fontsource using your package manager of choice. For example, if you want to use the Material Icons Round icon set, you would install the `@fontsource/material-icons-round` package. ### 2. Import Icon Set [#2-import-icon-set] In your application’s entry file or component, import the font variation you installed. For example: ```jsx import "@fontsource/material-icons"; import "@fontsource/material-icons-round"; import "@fontsource/material-icons-outlined"; import "@fontsource/material-icons-sharp"; import "@fontsource/material-icons-two-tone"; ``` ### 3. Apply CSS class [#3-apply-css-class] To ensure proper rendering of the icons, include the following CSS class in your HTML file: ```css .material-icons { font-family: 'Material Icons'; font-weight: normal; font-style: normal; font-size: 24px; /* Preferred icon size */ display: inline-block; line-height: 1; text-transform: none; letter-spacing: normal; word-wrap: normal; white-space: nowrap; direction: ltr; /* Support for all WebKit browsers. */ -webkit-font-smoothing: antialiased; /* Support for Safari and Chrome. */ text-rendering: optimizeLegibility; /* Support for Firefox. */ -moz-osx-font-smoothing: grayscale; /* Support for IE. */ font-feature-settings: 'liga'; } ``` You can learn more about styling Material Icons [here](https://developers.google.com/fonts/docs/material_icons#setup_method_2_self_hosting). --- # Material Symbols Source: /docs/getting-started/material-symbols # Material Symbols [#material-symbols] Fontsource now supports Material Symbols, a new icon set with variable font support. Material Symbols offers various icons with customizable attributes such as FILL, wght, GRAD, and opsz. This allows you to create dynamic and visually appealing icons in your web applications. ## Installation [#installation] To install Material Symbols from Fontsource, follow the steps below: ### 1. Install Icon Set [#1-install-icon-set] Install the desired icon set from Fontsource using your package manager of choice. For example, if you want to use the Material Symbols Round icon set, you would install the `@fontsource-variable/material-symbols-rounded` package. ### 2. Import Icon Set [#2-import-icon-set] In your application’s entry file or component, import the font variation you installed. For example: ```jsx import "@fontsource-variable/material-symbols-outlined"; import "@fontsource-variable/material-symbols-rounded"; import "@fontsource-variable/material-symbols-sharp"; ``` You can import individual axes or the whole set with these examples: ```jsx import "@fontsource-variable/material-symbols-outlined/fill.css"; import "@fontsource-variable/material-symbols-rounded/opsz.css"; import "@fontsource-variable/material-symbols-sharp/full.css"; ``` Please refer to the [Variable Fonts](/docs/getting-started/variable) guide for more information on using variable fonts. If you do not need the variable font support, you can import the standard font variation instead: ```jsx import "@fontsource/material-symbols-outlined"; import "@fontsource/material-symbols-rounded"; import "@fontsource/material-symbols-sharp"; ``` ### 3. Apply CSS class [#3-apply-css-class] To ensure proper rendering of the icons, include the following CSS class in your HTML file. You can use the same class or create different classes for each icon set: ```css .material-symbols-outlined { font-family: "Material Symbols Outlined"; font-weight: normal; font-style: normal; font-size: 24px; /* Preferred icon size */ display: inline-block; line-height: 1; text-transform: none; letter-spacing: normal; word-wrap: normal; white-space: nowrap; direction: ltr; } ``` By applying the `.material-symbols-outlined` class to the relevant elements, you can utilize the Material Symbols Outlined font in your application.
You can learn more about styling Material Symbols [here](https://developers.google.com/fonts/docs/material_symbols). --- # Migrating to V5 Source: /docs/getting-started/migrate-v5 # Migration Guide V5 [#migration-guide-v5] Fontsource V5 introduces several breaking changes that may require modifications to your existing codebase. This guide will help you migrate from the previous version to the latest version of Fontsource. Please review the following breaking changes and apply the necessary updates. ## Breaking Changes [#breaking-changes] ### Variable Font Package Names [#variable-font-package-names] Variable fonts are now split into separate packages to provide more flexibility and granular control. #### Before [#before] ```js import "@fontsource/nunito-sans/variable.css"; import "@fontsource/nunito-sans/variable-italic.css"; import "@fontsource/nunito-sans/variable-full.css"; import "@fontsource/nunito-sans/variable-full-italic.css"; ``` #### After [#after] ```js import "@fontsource-variable/nunito-sans"; import "@fontsource-variable/nunito-sans/wght-italic.css"; import "@fontsource-variable/nunito-sans/full.css"; import "@fontsource-variable/nunito-sans/full-italic.css"; ``` > **Note:** Please note that if you were previously using the `full` variant, it may no longer be available. We have introduced a new `standard` axis that is generated with a smaller subset of variable axes for improved performance and compatibility. > >
> > For more information about the new `standard` axis and its characteristics, you can refer to the [**Variable Fonts**](/docs/getting-started/variable#understanding-variable-axes) guide. Additionally, on each font’s page in the search directory, you can explore the import generator to see the available variants specific to that font. ### Variable Font Family Names [#variable-font-family-names] A mistake made the `font-family` names for variable fonts inconsistent with the rest of the packages. This has been fixed in V5, so you will need to update your CSS stylesheets. #### Before [#before-1] ```css body { font-family: "Nunito SansVariable", sans-serif; } ``` #### After [#after-1] ```css body { font-family: "Nunito Sans Variable", sans-serif; } ``` ### Renamed Variable Font Files [#renamed-variable-font-files] If you relied on the previous file names that used `wghtOnly`, you will need to update your code to only use `wght` instead. ### Rewritten Sass Integration [#rewritten-sass-integration] The Sass integration in Fontsource has been completely rewritten in V5. Please refer to the new Sass documentation for detailed usage instructions as there are many changes. Here’s a small example to showcase the difference: #### Before [#before-2] ```scss @include OpenSans.fontFace( $weight: 500, $display: fallback, $fontDir: "~@fontsource/open-sans/files" ); ``` #### After [#after-2] ```scss @include OpenSans.faces( $subsets: latin, $weights: (300, 400, 500, 800), $styles: all, $directory: "~@fontsource/open-sans/files" ); ``` ### Material Icons [#material-icons] The Material Icons package has been including the `.material-icons` class by default. This has been removed in V5, so you will need to add it manually to your codebase. You can find it in the [documentation](/docs/getting-started/material-icons) for reference. Additionally, `@fontsource/material-icons-rounded` has been renamed to `@fontsource/material-icons-round` to match the official package name. ### License Metadata [#license-metadata] A small change to the `metadata.json` file changes the `license` property from type `string` to a new license object. This has the added benefit of `LICENSE` files in each package due to the new stored details. #### Before [#before-3] ```json { ... "license": "https://fonts.google.com/attribution", ... } ``` #### After [#after-3] ```json { ... "license": { "type": "OFL-1.1", "url": "http://scripts.sil.org/OFL", "attribution": "Copyright " }, ... } ``` --- # Preloading Fonts Source: /docs/getting-started/preload # Preloading Fonts [#preloading-fonts] Preloading fonts is a technique used to load fonts before they’re required, which can improve your website’s performance. However, it’s essential to preload only critical fonts and subsets to avoid unnecessarily increasing initial load times. > **Note:** You can learn more about the `preload` link relation type in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload). To preload a font, you can use the `preload` link relation type in the `` of your HTML document. However, due to bundler constraints, you must manually import the URL to your font file. This is typically challenging since bundlers like Vite rewrite URLs to hashed filenames.
Instead, you can use the Vite [static asset directive](https://vite.dev/guide/assets.html#explicit-url-imports) `?url` to import the font file URL. For instance, the following code highlights how to preload the Open Sans font: ```jsx import '@fontsource-variable/open-sans'; import openSansWoff2 from '@fontsource-variable/open-sans/files/open-sans-latin-wght-normal.woff2?url'; const App = () => { return ( ); }; ``` > **Note:** Avoid preloading all font files in your project, as this may lead to increased initial load times. Only preload critical fonts and subsets that are essential for the initial page display, such as the latin subset only. > >
> > Additionally, preloading can have negative effects on Core Web Vitals if not used correctly. See the [Web Vitals](https://web.dev/articles/preload-critical-assets#effects_of_preloading_on_core_web_vitals) article for more information. --- # Sass Import Source: /docs/getting-started/sass-import # Sass Import [#sass-import] When using Fontsource in a Sass/SCSS project, you can import the CSS font stylesheets using the `@use` rule. ## Installation [#installation] For the most basic usage of importing Fontsource CSS stylesheets, you can use the `@use` rule in your Sass/SCSS file. Here’s an example of importing the Open Sans font: ```scss @use "pkg:@fontsource/open-sans/index.css"; ``` > **Note:** The `pkg:` prefix is required to import packages from the npm registry. You must use the `NodePackageImporter()` in your Sass compiler to resolve these imports. Learn more in the [Sass Introduction](/docs/getting-started/sass-introduction) guide. You can also import specific font variations if needed: ```scss @use "pkg:@fontsource/open-sans/300.css" as OpenSansLight; @use "pkg:@fontsource/open-sans/700-italic.css" as OpenSansBoldItalic; ``` ## Usage [#usage] Once you have imported the Fontsource stylesheets, the font styles will be available for use in your project. You can apply the imported font styles to elements using the font-family property in your CSS rules. Here’s an example: ```scss body { font-family: "Open Sans", sans-serif; } ``` --- # Sass Introduction Source: /docs/getting-started/sass-introduction # Introduction [#introduction] When using Fontsource in a Sass/SCSS project, you will need to configure your Sass compiler to resolve the [`pkg:`](https://sass-lang.com/documentation/at-rules/use/#pkg-ur-ls) import directive to resolve the font stylesheets from the NPM package. ## Configuration [#configuration] It is required to use Dart Sass `v1.71.0` or later to resolve the [`pkg:`](https://sass-lang.com/documentation/at-rules/use/#pkg-ur-ls) import directive. ### Command Line [#command-line] If you are using the command line to compile your Sass files, you can use the [`--pkg-importer=node`](https://sass-lang.com/documentation/cli/dart-sass/#pkg-importer-node) flag to resolve the imports. Here’s an example of how to compile a Sass file using the command line flag: ```sh sass --pkg-importer=node style.scss style.css ``` ### JavaScript API [#javascript-api] If you are using the JavaScript API to compile your Sass files, you can use the [`NodePackageImporter()`](https://sass-lang.com/documentation/js-api/classes/nodepackageimporter/) to resolve the imports. Here’s an example of how to configure the Sass compiler: ```js const sass = require('sass'); sass.compileString('@use "pkg:@fontsource-variable/roboto', { importers: [new sass.NodePackageImporter()] }); ``` ### Direct URLs [#direct-urls] If you cannot use the `pkg:` import directive, you can still import the Fontsource stylesheets using the direct URI to the CSS file. Here’s an example of importing the Open Sans font using the direct URL: ```scss // Adjust path as necessary. @use "../node_modules/@fontsource-utils/src/mixins.scss" as fontsource; @use "../node_modules/@fontsource-variable/recursive/scss/metadata.scss" as recursive; ``` ## Usage [#usage] Once configured, you can import Fontsource stylesheets using the `@use` rule in your Sass/SCSS files. * [Import Stylesheets](/docs/getting-started/sass-import) For more advanced usage, you can use the mixins to generate a highly customizable CSS file for your font. * [Faces Mixin](/docs/getting-started/faces-mixin) * [Generator Mixin](/docs/getting-started/generator-mixin) --- # Individual Subsets Source: /docs/getting-started/subsets # Individual Subsets [#individual-subsets] In the rare case that you need to import a specific subset of a font, you can do so by importing the subset’s CSS file. For example, if you only need the `latin` subset of the `Open Sans` font, you can import the `latin.css` file: ```js import "@fontsource/open-sans/latin.css"; import "@fontsource/open-sans/latin-ext-300.css"; import "@fontsource/open-sans/greek-700-italic.css"; ``` This is not available for variable fonts. > **Note:** We do not recommend using this method unless you have a specific reason to do so. The default CSS utilises the `unicode-range` property to only load the characters that are used on the page, which is more efficient than manually loading subsets. --- # Variable Fonts Source: /docs/getting-started/variable # Variable Fonts [#variable-fonts] Variable fonts allow designers and developers to use a single font file that contains multiple variations of the same font, such as different weights, widths, and styles. This can result in **smaller file sizes** and **more flexible design options**. Here’s how you can use variable fonts with Fontsource: ## 1. Install Package [#1-install-package] To use a variable font with Fontsource, you need to install the corresponding variable font package. For example, if you want to use the Nunito Sans variable font, you would install the `@fontsource-variable/nunito-sans` package: ```sh npm install @fontsource-variable/nunito-sans yarn add @fontsource-variable/nunito-sans pnpm add @fontsource-variable/nunito-sans bun add @fontsource-variable/nunito-sans ``` ## 2. Import the Font [#2-import-the-font] After installing the package, you can import the font into your project like this: ```jsx // Supports weights 200-1000 with one variable face per subset. import "@fontsource-variable/nunito-sans"; ``` This imports the default variable face, usually the normal style across the full weight range. The CSS also uses `unicode-range`, so browsers fetch only the character sets used on the page. If you want an italic style or a different set of axes, import the corresponding CSS file instead: ```jsx // Supports weights 200-1000 in italic style. import "@fontsource-variable/nunito-sans/wght-italic.css"; ``` ## 3. CSS [#3-css] Once the font is imported, you can use it in your CSS stylesheets just like any other font. The difference with variable fonts is that you can specify the specific axis values you want to use. Here’s an example: ```css body { font-family: "Nunito Sans Variable", sans-serif; font-weight: 500; font-variation-settings: "wdth" 75, "wght" 500; } ``` In this example, we are setting the font weight to `500` and the width axis to `75%` of the maximum width. Note that not all axes are supported by all variable fonts, so you will need to consult the font documentation to see which axes are available. ## 4. Fallbacks [#4-fallbacks] Optionally, if you want to use variable fonts but also support browsers that do not support them, you can use the `@supports` rule to provide a fallback. You will also need to import `@fontsource/nunito-sans` or any other font as the fallback, however, it is also fine to rely on default system fonts for this. Here’s an example: ```css body { font-family: "Nunito Sans", sans-serif; font-weight: 500; } @supports (font-variation-settings: normal) { body { font-family: "Nunito Sans Variable", sans-serif; font-weight: 500; font-variation-settings: "wdth" 75, "wght" 500; } } ``` This will only apply the font styles if the browser supports variable fonts (`font-variation-settings`). Otherwise, it will use the fallback font. ## Understanding Variable Axes [#understanding-variable-axes] Variable axes in fonts refer to the ability to adjust various visual characteristics of a font along a continuous spectrum. This allows for greater flexibility and control in fine-tuning the appearance of typography. ### Standard Axes [#standard-axes] Fontsource’s variable axes encompass a range of `standard` and `custom` options. The standard axes consist of a small subset of the most commonly used axes, including `[wght, wdth, slnt, opsz, ital]`. If you want to import these axes individually, you can do so using the following syntax: ```jsx import "@fontsource-variable/nunito-sans/wght.css"; import "@fontsource-variable/nunito-sans/wdth-italic.css"; import "@fontsource-variable/nunito-sans/opsz.css"; ``` However, if you want to import multiple standard axes, it is recommended to use the `standard` CSS file instead: ```jsx import "@fontsource-variable/nunito-sans/standard.css"; import "@fontsource-variable/nunito-sans/standard-italic.css"; ``` > **Note:** Each import includes the `wght` axis as multiple imports of different axes are not supported. Therefore, you must use a single import when importing variable fonts. ### Custom Axes [#custom-axes] In addition to the standard axes, Fontsource provides a variety of custom options. To import these axes individually, you can use the following syntax: ```jsx import "@fontsource-variable/nunito-sans/grad.css"; import "@fontsource-variable/nunito-sans/ytuc.css"; import "@fontsource-variable/nunito-sans/xtra.css"; ``` > **Note:** Please note that not all fonts support these custom axes. To see which axes are available for a specific font, refer to the font’s page in the search directory. You can also explore the [**Axis Registry**](https://fonts.google.com/variablefonts#axis-definitions) to learn more about these various axes. These custom axes offer additional opportunities for fine-grained customization beyond the standard options, providing more specialized variations. If you want to import **all** available axes, you can use the `full` CSS file: ```jsx import "@fontsource-variable/nunito-sans/full.css"; import "@fontsource-variable/nunito-sans/full-italic.css"; ``` --- # Angular Source: /docs/guides/angular # Angular [#angular] Fontsource packages keep font files versioned with your Angular application and let its build pipeline bundle only the variants you import. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it globally [#2-import-it-globally] Import the font from your application entry point so it is available to every component: ```ts // src/main.ts import "@fontsource-variable/open-sans/wght.css"; import { bootstrapApplication } from "@angular/platform-browser"; import { AppComponent } from "./app/app.component"; bootstrapApplication(AppComponent).catch((error) => console.error(error)); ``` The `wght.css` entry includes the variable weight axis. If you use a static package instead, import only the weights and styles your application needs. ## 3. Apply the font [#3-apply-the-font] Use the package’s font family name in your global stylesheet: ```css /* src/styles.css */ body { margin: 0; font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` ## Existing NgModule applications [#existing-ngmodule-applications] NgModules remain supported for existing Angular applications. The same import can live in `main.ts` or alongside the root `AppModule`; Fontsource does not require standalone components. ```ts import "@fontsource-variable/open-sans/wght.css"; import { NgModule } from "@angular/core"; import { BrowserModule } from "@angular/platform-browser"; import { AppComponent } from "./app.component"; @NgModule({ declarations: [AppComponent], imports: [BrowserModule], bootstrap: [AppComponent], }) export class AppModule {} ``` See Angular’s [NgModule guide](https://angular.dev/guide/ngmodules/overview) for the current recommendation for new and existing applications. --- # Framework Guides Source: /docs/guides # Framework Guides [#framework-guides] Choose a framework or tool. For package setup, see the [installation guide](/docs/getting-started/install). --- # Next.js Source: /docs/guides/nextjs # Next.js [#nextjs] Fontsource packages give you explicit, versioned control over the font files, weights, styles, subsets, and variable axes included in your Next.js build. The browser serves those assets from the same deployment as your application. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from the root [#2-import-it-from-the-root] ### App Router [#app-router] Import the font CSS from your root layout: ```tsx // app/layout.tsx import "@fontsource-variable/open-sans/wght.css"; import "./globals.css"; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( {children} ); } ``` You can instead import a font from a nested `layout.tsx` when only one route segment needs it. ### Pages Router [#pages-router] Import the font from your custom App component: ```tsx // pages/_app.tsx import type { AppProps } from "next/app"; import "@fontsource-variable/open-sans/wght.css"; import "../styles/globals.css"; export default function App({ Component, pageProps }: AppProps) { return ; } ``` ## 3. Apply the font [#3-apply-the-font] ```css /* app/globals.css or styles/globals.css */ body { font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` ## Fontsource or `next/font`? [#fontsource-or-nextfont] Both approaches self-host font files and avoid browser requests to Google. `next/font` downloads supported Google Fonts at build time and generates the loading CSS for you. Use Fontsource when you want fonts to be normal package dependencies, need fonts outside the Google Fonts catalog, or want direct control over package versions, CSS, subsets, axes, and font files. See the [Next.js font documentation](https://nextjs.org/docs/app/getting-started/fonts) for the built-in alternative. --- # Qwik Source: /docs/guides/qwik # Qwik [#qwik] Qwik uses Vite, so Fontsource CSS imports and their referenced font files are processed by the existing application build. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from the root layout [#2-import-it-from-the-root-layout] Add the package import to `src/routes/layout.tsx` to make the font available throughout the application: ```tsx import { component$, Slot } from "@builder.io/qwik"; import "@fontsource-variable/open-sans/wght.css"; export default component$(() => { return (
); }); ``` Qwik City renders every page inside this root layout. You can instead import a font from a nested layout or component when only that part of the application needs it. ## 3. Apply the font [#3-apply-the-font] Add the family to `src/global.css`, which a Qwik starter imports from its root component: ```css body { font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` For component-only styles, the same family can be used with `useStylesScoped$()`: ```tsx import { component$, useStylesScoped$ } from "@builder.io/qwik"; import "@fontsource-variable/open-sans/wght.css"; export default component$(() => { useStylesScoped$(` .heading { font-family: "Open Sans Variable", sans-serif; font-weight: 600; } `); return

Hello Qwik

; }); ``` See Qwik City’s [project structure](https://qwik.dev/docs/project-structure/) and [layout documentation](https://qwik.dev/docs/layout/) for more about these files. --- # React Router Source: /docs/guides/react-router # React Router [#react-router] React Router Framework Mode uses Vite, so Fontsource package CSS can be imported directly from a route module. Vite bundles the CSS and emits the font files as self-hosted, hashed assets. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from the root route [#2-import-it-from-the-root-route] ```tsx // app/root.tsx import "@fontsource-variable/open-sans/wght.css"; import "./app.css"; // Keep the rest of your root route unchanged. ``` The root route is the parent of every other route, so this import makes the font available throughout the application. ## 3. Apply the font [#3-apply-the-font] ```css /* app/app.css */ body { font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` ## Load a font for one route [#load-a-font-for-one-route] Import the package CSS from an individual route when the font is used only there: ```tsx // app/routes/editor.tsx import "@fontsource/jetbrains-mono/400.css"; export default function Editor() { return const ready = true;; } ``` For explicit route stylesheet links, Vite can return a package CSS URL: ```tsx import fontCssHref from "@fontsource/jetbrains-mono/400.css?url"; export function links() { return [{ rel: "stylesheet", href: fontCssHref }]; } ``` The `links` approach requires the root document to render React Router’s `` component, as the default framework template does. See React Router’s [styling guide](https://reactrouter.com/explanation/styling) for the available CSS patterns. --- # Remix Source: /docs/guides/remix # Remix [#remix] Remix applications built with Vite can import Fontsource CSS directly. Vite bundles the CSS and emits its font files as versioned application assets. > Starting a new project? Remix’s current framework features now live in React > Router. See the [React Router guide](/docs/guides/react-router) for that > setup. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from the root route [#2-import-it-from-the-root-route] ```tsx // app/root.tsx import "@fontsource-variable/open-sans/wght.css"; import "./app.css"; // Keep the rest of your root route unchanged. ``` CSS side-effect imports work without the former `@remix-run/css-bundle` package when using Remix Vite. Importing from `app/root.tsx` makes the font available to every route. ## 3. Apply the font [#3-apply-the-font] ```css /* app/app.css */ body { font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` Import only the weights, styles, or variable axes you use. The [package installation guide](/docs/getting-started/install) lists the available entry points. See Remix’s [CSS import documentation](https://v2.remix.run/docs/styling/css-imports) for more about Vite CSS handling. --- # Storybook Source: /docs/guides/storybook # Storybook [#storybook] Storybook renders stories in a separate preview document. Importing a Fontsource package from the preview configuration makes the same self-hosted font available to every story and docs page. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/inter yarn add @fontsource-variable/inter pnpm add @fontsource-variable/inter bun add @fontsource-variable/inter ``` ## 2. Import it from the preview configuration [#2-import-it-from-the-preview-configuration] Add the font CSS before your existing preview export: ```ts // .storybook/preview.ts import "@fontsource-variable/inter/wght.css"; import "./preview.css"; // Keep your existing Storybook preview configuration below. export default { parameters: {}, }; ``` ## 3. Apply the font [#3-apply-the-font] ```css /* .storybook/preview.css */ body { font-family: "Inter Variable", sans-serif; } ``` If your application already has a global stylesheet that applies the family, import that stylesheet from `preview.ts` after the Fontsource package instead of creating `preview.css`. For a font used by only one component, import its package entry beside that component. Storybook will process the import through its configured Vite or Webpack builder. See Storybook’s [webfont documentation](https://storybook.js.org/docs/configure/styling-and-css/#adding-webfonts) for the preview-file integration. --- # SvelteKit Source: /docs/guides/svelte # SvelteKit [#sveltekit] Fontsource packages are handled by SvelteKit’s Vite build, keeping the font files self-hosted and versioned with the rest of your application. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/inter yarn add @fontsource-variable/inter pnpm add @fontsource-variable/inter bun add @fontsource-variable/inter ``` ## 2. Import it from the root layout [#2-import-it-from-the-root-layout] For a current SvelteKit application, import the font in `src/routes/+layout.svelte`: ```svelte {@render children()} ``` This makes the font available across every page. To limit a font to one section of the application, import it from that route’s `+layout.svelte` instead. ## Import through a global stylesheet [#import-through-a-global-stylesheet] You can also keep all global typography in one CSS file: ```css /* src/styles/global.css */ @import "@fontsource-variable/inter/wght.css"; body { margin: 0; font-family: "Inter Variable", sans-serif; } h1 { font-weight: 700; } ``` ```svelte {@render children()} ``` Svelte 4 applications can keep their existing `` layout syntax. In Svelte 5, snippets and `{@render children()}` replace legacy slots. --- # Vite Source: /docs/guides/vite # Vite [#vite] Vite can import Fontsource CSS without additional configuration. It resolves the CSS `url()` references, emits the font files as hashed assets, and keeps them on the same origin as your application. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from your entry point [#2-import-it-from-your-entry-point] ```ts // src/main.ts import "@fontsource-variable/open-sans/wght.css"; import "./style.css"; ``` The variable package’s `wght.css` entry covers its full weight range with one font file per subset. For a static package, import only the variants you use: ```ts import "@fontsource/open-sans/400.css"; import "@fontsource/open-sans/700.css"; ``` ## 3. Apply the font [#3-apply-the-font] ```css /* src/style.css */ body { font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` Vite rebases the font URLs found in the package CSS automatically, so you do not need to copy files into `public/` or configure an asset loader. ## Preload a critical font [#preload-a-critical-font] When a font is critical to the first screen, Vite’s `?url` import returns its final build URL: ```ts import openSansUrl from "@fontsource-variable/open-sans/files/open-sans-latin-wght-normal.woff2?url"; ``` Pass that URL to your framework’s document head or preload component. Preload only the subset and style needed immediately; unnecessary preloads compete with other critical resources. See the dedicated [preloading guide](/docs/getting-started/preload) and Vite’s [CSS features](https://vite.dev/guide/features.html#css) and [static asset handling](https://vite.dev/guide/assets.html#explicit-url-imports) for more detail. --- # Vue Source: /docs/guides/vue # Vue [#vue] Fontsource packages work with Vue’s standard Vite setup. The font files remain self-hosted and are emitted with the rest of your application assets. ## 1. Install the font [#1-install-the-font] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ## 2. Import it from the application entry point [#2-import-it-from-the-application-entry-point] ```ts // src/main.ts import { createApp } from "vue"; import "@fontsource-variable/open-sans/wght.css"; import "./style.css"; import App from "./App.vue"; createApp(App).mount("#app"); ``` Importing from `main.ts` makes the font available to the whole application. Import it from an individual component or route instead when you want the font in a separate bundle. ## 3. Apply the font [#3-apply-the-font] ```css /* src/style.css */ body { margin: 0; font-family: "Open Sans Variable", sans-serif; } h1 { font-weight: 700; } ``` If you use a static package, import only the weights and styles you need: ```ts import "@fontsource/open-sans/400.css"; import "@fontsource/open-sans/700.css"; ``` --- # Webpack Source: /docs/guides/webpack # Webpack [#webpack] Webpack can bundle Fontsource CSS and emit its referenced font files as versioned application assets. Webpack 5’s built-in Asset Modules replace the former `file-loader` setup. ## 1. Install the font and CSS loaders [#1-install-the-font-and-css-loaders] ```sh npm install @fontsource-variable/open-sans yarn add @fontsource-variable/open-sans pnpm add @fontsource-variable/open-sans bun add @fontsource-variable/open-sans ``` ```sh npm install -D style-loader css-loader yarn add -D style-loader css-loader pnpm add -D style-loader css-loader bun add -D style-loader css-loader ``` ## 2. Configure Webpack [#2-configure-webpack] Add rules for CSS and font assets: ```js // webpack.config.js module.exports = { module: { rules: [ { test: /\.css$/i, use: ["style-loader", "css-loader"], }, { test: /\.(woff2?|eot|ttf|otf)$/i, type: "asset/resource", }, ], }, }; ``` `css-loader` resolves the `url()` references in Fontsource CSS. `style-loader` adds the resulting stylesheet to the page. The asset rule emits the referenced font files without an additional loader. ## 3. Import and apply the font [#3-import-and-apply-the-font] ```js // src/index.js import "@fontsource-variable/open-sans/wght.css"; import "./styles.css"; ``` ```css /* src/styles.css */ body { font-family: "Open Sans Variable", sans-serif; } ``` For production builds that extract CSS into separate files, use your existing CSS extraction plugin in place of `style-loader`. See Webpack’s [Asset Modules guide](https://webpack.js.org/guides/asset-modules/) and [`style-loader` documentation](https://webpack.js.org/loaders/style-loader/) for the underlying configuration.