# 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\<string, AxisRegistryItem> | Axis tag object |

<br />

#### 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\<string, string> | 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\<string, object> | File variants        |

<br />

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.

<br />

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\<DownloadStats> | Variable download counts |

<br />

#### 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`


---

# 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\<string, AxesData> | Axis data   |

<br />

#### 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\<string>    | Latest variable NPM version                   |
| variable       | Optional\<string\[]> | 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 all of its font files, allowing for niche use cases where a stable font file link is required. All files are versioned according to [Semver](https://semver.org/), and using a specific version tag will give you longer lived caches.

> **Note:** We recommend self-hosting your fonts if possible, but we understand there are suitable use cases for a CDN.

## Usage [#usage]

To leverage the Fontsource CDN for your project, you can use the import generator provided on the install page of each font. For example, to use [Roboto Flex](/fonts/roboto-flex/cdn), you can access its import generator to generate the relevant URLs and CSS necessary for your projec

## URL Formats [#url-formats]

The Fontsource CDN provides two primary URL formats for accessing font files:

### Static URLs [#static-urls]

Static font URLs follow this pattern:

* `https://cdn.jsdelivr.net/fontsource/fonts/{id}@{version}/{subset}-{weight}-{style}.{extension}`

### Variable Fonts URLs [#variable-fonts-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:

* 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, you can use the **Advanced*&#x2A; tab on each &#x2A;*[Install](https://fontsource.org/fonts/open-sans/install)** page to generate custom `@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 provides a straightforward process for installing fonts into your web application. This guide will walk you through the installation steps.

## 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.

> **Variable Fonts**
>
> If your chosen font supports variable fonts, Fontsource **highly recommends** using them, especially when working with multiple weights, as it helps reduce bundle sizes. To learn more about using variable fonts, refer to the dedicated [Variable Fonts](/docs/getting-started/variable) guide.

## 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 font package. For example, to install the Open Sans font, run the following command:

```sh
npm install @fontsource/open-sans
yarn add @fontsource/open-sans
pnpm add @fontsource/open-sans
bun add @fontsource/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.

#### Default Import [#default-import]

The most straightforward way to import a font is using its package name directly. This will import the most common weight, which is **400** for most fonts.

```jsx
import "@fontsource/open-sans"; // Defaults to weight 400.
```

#### Specific Weights and Styles [#specific-weights-and-styles]

To minimize your bundle size, it is recommended to import only the specific weights and styles you need. A single import statement will load **one** font file.

```jsx
import "@fontsource/open-sans/300.css"; // Includes weight 300.
import "@fontsource/open-sans/900-italic.css"; // Includes weight 900 in italic style.
```

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 to use **all** available weights and styles, you must import each one individually. Due to the large file size, this is generally not recommended unless you have a specific use case.

> **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.

<br />

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.
>
> <br />
>
> 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 <attribution>"
  },
  ...
}
```


---

# 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 `<head>` 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.

<br />

Instead, you can use the Vite [static asset directive](https://vitejs.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 (
    <html lang="en">
      <head>
        <link rel="preload" as="font" type="font/woff2" href={openSansWoff2} crossorigin="anonymous" />
      </head>
    </html>
  );
};
```

> **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.
>
> <br />
>
> 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 in a single small file.
import "@fontsource-variable/nunito-sans";
```

This will import the standard weight of the font. If you want to use a specific weight or variation, you can 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]

To integrate Fontsource into your Angular project, follow the steps below.

## 1. Installation [#1-installation]

First, install the font package you want to use:

```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 in Main Entry File [#2-import-in-main-entry-file]

For Angular 17+ projects, the recommended approach is to import fonts in your main entry file (`main.ts`):

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';

import '@fontsource-variable/open-sans/wght.css';

bootstrapApplication(AppComponent, {
  providers: [
    // ...
  ]
}).catch(err => console.error(err));
```

## 3. Alternative: Component-Level Import [#3-alternative-component-level-import]

You can also import fonts directly in individual components:

```ts
import { Component } from '@angular/core';

import '@fontsource-variable/open-sans/wght.css';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <h1>Welcome to {{ title }}!</h1>
  `,
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my-app';
}
```

## 4. Legacy Installation [#4-legacy-installation]

If you’re using the traditional module-based Angular architecture (pre-Angular 17), you can import fonts in your `AppModule`:

```ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import '@fontsource-variable/open-sans/wght.css';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }
```

## 5. CSS Usage [#5-css-usage]

Once imported, you can use the font in your component stylesheets:

```css
/* app.component.css */
h1 {
  font-family: "Open Sans Variable", sans-serif;
  font-weight: 600;
}

.content {
  font-family: "Open Sans Variable", sans-serif;
  font-weight: 400;
}
```

## 6. Global Styles [#6-global-styles]

For application-wide font usage, add the font family to your global styles (`styles.css`):

```css
/* styles.css */
body {
  font-family: "Open Sans Variable", sans-serif;
  margin: 0;
  padding: 0;
}
```


---

# Next.js

Source: /docs/guides/nextjs

# Next.js [#nextjs]

Next.js is a React framework for building web applications. Importing fonts depends on the router you are using. Below are the steps to import fonts into a Next.js project.

## App Router [#app-router]

To import fonts into a Next.js project using the [App Router](https://nextjs.org/docs/app), you can simply import the CSS file directly into your root layout file.

### 1. Installation [#1-installation]

```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 CSS [#2-import-css]

Modify `app/layout.tsx` to include the following code:

```tsx
import "@fontsource-variable/open-sans/wght.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

> **Note:** You can also import fonts in individual `layout.tsx` or `page.tsx` files to scope them to specific routes.

### 3. Usage [#3-usage]

You can now use the imported fonts in your Next.js project.

```css
h1 {
  font-family: "Open Sans Variable", sans-serif;
}
```

## Pages Router [#pages-router]

With the [Pages Router](https://nextjs.org/docs/pages/building-your-application/routing/custom-app), you can import fonts in your custom `_app.tsx` file.

### 1. Installation [#1-installation-1]

```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 CSS [#2-import-css-1]

Modify `_app.tsx` to include the following code:

```tsx
import "@fontsource-variable/open-sans/wght.css";

function MyApp({ Component, pageProps }: { Component: any; pageProps: any }) {
  return <Component {...pageProps} />;
}

export default MyApp;
```

> **Note:** You can also import fonts in individual page components, but the CSS will only be present within that page and not globally.

### 3. Usage [#3-usage-1]

You can now use the imported fonts in your Next.js project.

```css
h1 {
  font-family: "Open Sans Variable", sans-serif;
}
```

## Comparison to `next/font` [#comparison-to-nextfont]

Next.js offers a built-in way to load fonts using the `next/font` package. This package serves as a straightforward alternative to Fontsource with a simple setup. It embeds the CSS from the Google Fonts API, eliminating an additional round-trip response. It performs well for most use cases and is a good choice if you do not need to customise the font loading behaviour.

We recommend using Fontsource if you need more control over versioning your dependencies and do not want an invisible abstraction over the Google Fonts API. We also offer an escape hatch to directly modify the `@font-face` rules suitable for more advanced use cases.


---

# Qwik

Source: /docs/guides/qwik

# Qwik [#qwik]

To use Fontsource with a [Qwik City](https://qwik.builder.io) project, it is suggested to use the `/routes/layout.tsx` file.

## 1. Installation [#1-installation]

Once you [install](https://fontsource.org/docs/getting-started/install) the Fontsource package of your choice, you can import the chosen font variant into `routes/layout.tsx`:

```tsx
import { component$ } from "@builder.io/qwik";
import "@fontsource-variable/open-sans/wght.css";

export default component$(() => {
  return (
    <>
      <Header />
      <main>
        <Slot />
      </main>
      <Footer />
    </>
  );
});
```

> **Note:** Alternatively, you can import the font in **index.tsx** or any other component file and it should have the same effect.

## 2. Usage [#2-usage]

You can now use the imported fonts in your Qwik City project. Here’s an example of the Open Sans Variable font being applied to an `h1` selector.

```css
h1 {
  font-family: "Open Sans Variable", sans-serif;
}
```

### Scoped Component Fonts [#scoped-component-fonts]

To use Qwik’s scoped CSS functionality, you can use the font declaration in the `useStylesScoped$()` hook from Qwik.

```tsx
import { component$, useStylesScoped$ } from "@builder.io/qwik";
import "@fontsource-variable/open-sans";

export default component$(() => {
  useStylesScoped$(`
      .heading {
        font-family: "Open Sans Variable", sans-serif;
        font-weight: 500;
      }
    `);
  return (
    <>
        <h1 class="heading">
          Scoped heading using Open Sans with 500 font weight!
        </h1>
    </>
  );
});
```

You can opt out of this scoped behavior by using Qwik’s `:global()` selector.

## 3. Extensibility [#3-extensibility]

By default, Qwik works well with Fontsource out of the box. This even includes [lazy-loadable references](https://qwik.builder.io/docs/components/styles/#usestyles) to component styles with `useStyles$()`.


---

# Remix

Source: /docs/guides/remix

# Remix [#remix]

Remix is a full-stack JavaScript framework for building web applications. Importing fonts depends on the compiler you are using. Below are the steps to import fonts into a Remix project.

## Vite Compiler [#vite-compiler]

To import fonts into a Remix project using the Vite compiler, you can simply import the CSS file directly into your `root.tsx` file.

### 1. Import CSS [#1-import-css]

Modify `root.tsx` to include the following code:

```tsx
import "@fontsource-variable/open-sans/wght.css";
```

> **Note:** You **MUST** include the `.css` extension when importing the file or you will get an error.

### 2. Usage [#2-usage]

You can now use the imported fonts in your Remix.js project.

```css
h1 {
  font-family: "Open Sans Variable", sans-serif;
}
```

## Classic Remix Compiler [#classic-remix-compiler]

With the Classic Remix Compiler, you can leverage the CSS bundler plugin built into the framework.

### 1. Install the plugin [#1-install-the-plugin]

```sh
npm install @remix-run/css-bundle
yarn add @remix-run/css-bundle
pnpm add @remix-run/css-bundle
bun add @remix-run/css-bundle
```

### 2. Configure the plugin [#2-configure-the-plugin]

Modify `root.tsx` to include the following code:

```tsx
import { cssBundleHref } from "@remix-run/css-bundle";
import type { LinksFunction } from "@remix-run/node";

import "@fontsource-variable/open-sans/wght.css";

export const links: LinksFunction = () => {
  return [
    ...(cssBundleHref
      ? [{ rel: "stylesheet", href: cssBundleHref }]
      : []),
    // ...
  ];
};
```

### 3. Usage [#3-usage]

You can now use the imported fonts in your Remix.js project.

```css
h1 {
  font-family: "Open Sans Variable", sans-serif;
}
```

Read the official documentation on the plugin [here](https://remix.run/docs/en/main/guides/styling#css-bundling).


---

# SvelteKit

Source: /docs/guides/svelte

# SvelteKit [#sveltekit]

To include Fontsource into your Svelte / SvelteKit project and apply it to your application’s typography, follow the steps below.

## Installation [#installation]

First, install your chosen font package:

```sh
npm install @fontsource-variable/inter
yarn add @fontsource-variable/inter
pnpm add @fontsource-variable/inter
bun add @fontsource-variable/inter
```

## 1. Layout Import [#1-layout-import]

Import fonts in your root layout for application-wide availability:

```html
<!-- src/routes/+layout.svelte -->
<script>
  import '@fontsource-variable/inter/wght.css';
</script>

<main>
  <slot />
</main>

<style>
  :global(body) {
    font-family: 'Inter Variable', sans-serif;
    margin: 0;
  }

  :global(h1, h2, h3, h4, h5, h6) {
    font-family: 'Inter Variable', sans-serif;
    font-weight: 600;
  }
</style>
```

## 2. CSS File Import [#2-css-file-import]

Create a global CSS file and import it in your layout:

```css
/* src/styles/global.css */
@import '@fontsource-variable/inter/wght.css';

body {
  font-family: 'Inter Variable', sans-serif;
  margin: 0;
  line-height: 1.6;
}

h1, h2, h3, h4, h5, h6 {
  font-family: 'Inter Variable', sans-serif;
  font-weight: 600;
}
```

```html
<!-- src/routes/+layout.svelte -->
<script>
  import '../styles/global.css';
</script>

<main>
  <slot />
</main>
```

## 3. Component-Level Import [#3-component-level-import]

For better code splitting, import fonts in specific components or routes:

```html
<!-- src/routes/blog/+layout.svelte -->
<script>
  import '@fontsource/playfair-display/700.css';
  import '@fontsource-variable/inter/wght.css';
</script>

<article>
  <slot />
</article>

<style>
  article :global(h1) {
    font-family: 'Playfair Display', serif;
    font-weight: 700;
  }

  article :global(p) {
    font-family: 'Inter Variable', sans-serif;
    font-weight: 400;
  }
</style>
```


---

# Vue.js

Source: /docs/guides/vue

# Vue.js [#vuejs]

To include Fontsource into your Vue.js project, you can import the Fontsource files into your entry point with the appropriate bundler setup.

## Installation [#installation]

```js
import { createApp } from "vue";

import "@fontsource-variable/open-sans/wght.css";

import App from "./App.vue";

createApp(App).mount("#app");
```


---

# Webpack

Source: /docs/guides/webpack

# Webpack [#webpack]

To use Fontsource with Webpack, you’ll need to configure your Webpack project to handle font files and include Fontsource in the bundle. Follow the steps below to set it up.

## Installation [#installation]

### 1. Install the loaders [#1-install-the-loaders]

```sh
npm install css-loader file-loader
yarn add css-loader file-loader
pnpm add css-loader file-loader
bun add css-loader file-loader
```

### 2. Configure the loaders [#2-configure-the-loaders]

Modify `webpack.config.js` to include the following configuration:

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/,
        use: ["file-loader"],
      },
      {
        test: /\.css$/i,
        use: ["css-loader"],
      },
    ],
  },
};
```

### 3. Import the font [#3-import-the-font]

Import the font in your entry file or component:

```js
import "@fontsource-variable/open-sans/wght.css";
// You should be able to import other CSS files too
import "./styles.css"

// Your application code goes here
```