---
url: /api/plugin-fonts.md
description: >-
  Generated API reference for @pikacss/plugin-fonts from exported surface and
  JSDoc.
---

# Plugin Fonts API reference

* Package: `@pikacss/plugin-fonts`
* Generated from the exported surface and JSDoc in `packages/plugin-fonts/src/index.ts`.
* Source files: `packages/plugin-fonts/src/index.ts`, `packages/plugin-fonts/src/provider-options.ts`, `packages/plugin-fonts/src/providers.ts`

## Package summary

Web font integration.

Use [Fonts plugin](/official-plugins/fonts) when you need conceptual usage guidance instead of exact symbol lookup.

## Functions

### defineFontsProvider(provider) {#function-definefontsprovider-provider}

Identity helper that defines a font provider with full type inference.

| Parameter | Type | Description |
|---|---|---|
| `provider` | `T` | The provider definition object. |

**Returns:** `T` - The same provider definition, typed as `T`.

**Remarks:**

Provides type safety without any runtime transformation.

```ts
const myProvider = defineFontsProvider({
  buildImportUrls(fonts, ctx) {
    return fonts.map(f => `https://cdn.example.com/css?family=${f.name}`)
  },
})
```

### fonts() {#function-fonts}

Creates the fonts engine plugin for web-font integration.

**Returns:** `EnginePlugin` - An engine plugin that registers font imports, `@font-face` preflights, CSS variables, and `font-<token>` shortcuts.

**Remarks:**

Reads its configuration from the `fonts` key in the engine config. Google Fonts, Bunny Fonts, and Fontshare resolve through unifont at build time with a legacy stylesheet fallback; Coollabs and custom providers keep the stylesheet-provider path.

```ts
import { fonts } from '@pikacss/plugin-fonts'
import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  engine: {
    plugins: [fonts()],
    fonts: {
      provider: 'google',
      fonts: { sans: 'Inter:400,600,700' },
    },
  },
})
```

## Constants

### builtInFontsProviders {#const-builtinfontsproviders}

Registry mapping each built-in provider name to its implementation.

**Remarks:**

Includes Google Fonts, Bunny Fonts, Fontshare, Coollabs (self-hosted Google proxy), and `none` (no-op).

```ts
const urls = builtInFontsProviders.google.buildImportUrls?.(fonts, ctx)
```

## Types

### EffectiveFontsProviderOptions {#type-effectivefontsprovideroptions}

Effective provider option map passed to provider execution after defaults, overrides, and deletion markers are resolved.

**Type:** `Partial<Record<string, FontsProviderOptionValue>>`

### FontFaceDefinition {#interface-fontfacedefinition}

Describes a raw CSS `@font-face` declaration injected as a preflight.

| Property | Type | Description | Default |
|---|---|---|---|
| `fontFamily` | `string` | The `font-family` name for the `@font-face` rule. | — |
| `src` | `string \| string[]` | One or more `src` descriptors (e.g. `url(...)` expressions). | — |
| `fontDisplay?` | `string` | CSS `font-display` descriptor for this face. | `undefined` |
| `fontWeight?` | `string \| number` | CSS `font-weight` descriptor, such as `'400'` or `'100 900'` for variable fonts. | `undefined` |
| `fontStyle?` | `string` | CSS `font-style` descriptor (e.g. `'normal'`, `'italic'`). | `undefined` |
| `fontStretch?` | `string` | CSS `font-stretch` descriptor (e.g. `'condensed'`, `'75% 125%'`). | `undefined` |
| `unicodeRange?` | `string \| string[]` | CSS `unicode-range` descriptor to limit the character set. | `undefined` |

**Remarks:**

Each definition produces one `@font-face` block. Use this for self-hosted fonts or fonts that do not come from a provider URL.

```ts
const face: FontFaceDefinition = {
  fontFamily: 'MyFont',
  src: 'url(/fonts/MyFont.woff2) format("woff2")',
  fontWeight: '400 700',
  fontDisplay: 'swap',
}
```

### FontFamilyEntry {#type-fontfamilyentry}

A font entry — either a shorthand string or a full metadata object.

**Type:** `string | FontMeta`

**Remarks:**

Strings are parsed as `'Name'` or `'Name:weight1,weight2'`. Use `FontMeta` when you need italic or provider overrides.

```ts
const simple: FontFamilyEntry = 'Roboto'
const withWeights: FontFamilyEntry = 'Roboto:400,700'
const detailed: FontFamilyEntry = { name: 'Roboto', weights: [400, 700], italic: true }
```

### FontMeta {#interface-fontmeta}

Detailed metadata for a font family entry.

| Property | Type | Description | Default |
|---|---|---|---|
| `name` | `string` | Font family name as expected by the provider (e.g. `'Inter'`). | — |
| `weights?` | `Array<string \| number>` | Font weight values to load from the provider. | `[]` |
| `italic?` | `boolean` | Whether to include italic variants for the requested weights. | `false` |
| `provider?` | `FontsProvider` | Provider override for this font, taking precedence over the global `provider` option. | `undefined` |
| `providerOptions?` | `FontsProviderOptions` | Provider-specific overrides for this font. These are shallow-merged over the matching global `providerOptions` defaults. Explicit `null` or `undefined` values delete an inherited option; deletion markers are removed before provider execution. | `undefined` |

**Remarks:**

Use this form instead of a plain string when you need to specify weights, italic variants, or a per-font provider override.

```ts
const font: FontMeta = {
  name: 'Inter',
  weights: [400, 600, 700],
  italic: true,
  provider: 'bunny',
}
```

### FontsPluginOptions {#interface-fontspluginoptions}

Configuration options for the fonts plugin.

| Property | Type | Description | Default |
|---|---|---|---|
| `provider?` | `FontsProvider` | Default font provider used for all font entries that do not specify their own. | `'google'` |
| `fonts?` | `Record<string, FontFamilyEntry \| FontFamilyEntry[]>` | Font families grouped by shortcut token. Each token produces a `font-<token>` CSS shortcut. | `{}` |
| `families?` | `Record<string, string \| string[]>` | Raw `font-family` CSS stacks grouped by shortcut token; no provider loading is performed. | `{}` |
| `imports?` | `string \| string[]` | Additional stylesheet URLs, each wrapped in an `@import url("...")` rule and injected before legacy/custom provider imports. | `[]` |
| `faces?` | `FontFaceDefinition[]` | Custom `@font-face` definitions injected as preflight CSS. | `[]` |
| `display?` | `string` | CSS `font-display` value applied to provider-resolved `@font-face` rules and legacy provider imports. | `'swap'` |
| `providers?` | `Record<string, FontsProviderDefinition>` | Custom font provider implementations keyed by provider name. | `{}` |
| `providerOptions?` | `Record<string, FontsProviderOptions>` | Provider-level defaults keyed by provider name. Each font entry receives one active effective option map formed by applying its `FontMeta.providerOptions` overrides to these defaults and removing nullish deletion markers before any provider path runs. | `{}` |

**Remarks:**

Set these under the `fonts` key in your engine config. Google, Bunny, and Fontshare entries are resolved through unifont into `@font-face` rules at build time; legacy/custom providers remain stylesheet imports. The plugin also registers `font-<token>` shortcuts.

```ts
const options: FontsPluginOptions = {
  provider: 'google',
  display: 'swap',
  fonts: {
    sans: 'Inter:400,600,700',
    mono: 'Fira Code:400,700',
  },
}
```

### FontsProvider {#type-fontsprovider}

Identifier for a font provider — either a built-in name or a custom string.

**Type:** `BuiltinFontsProvider | (string & {})`

**Remarks:**

Custom strings must have a matching entry in `FontsPluginOptions.providers` to take effect.

```ts
const builtin: FontsProvider = 'bunny'
const custom: FontsProvider = 'my-cdn'
```

### FontsProviderContext {#interface-fontsprovidercontext}

Runtime context passed to a provider's `buildImportUrls` callback.

| Property | Type | Description | Default |
|---|---|---|---|
| `provider` | `FontsProvider` | The provider identifier this context belongs to. | — |
| `display` | `string` | CSS `font-display` value applied to all fonts from this provider. | — |

**Remarks:**

Assembled from the resolved plugin configuration during engine setup.

```ts
const ctx: FontsProviderContext = {
  provider: 'google',
  display: 'swap',
}
```

### FontsProviderDefinition {#interface-fontsproviderdefinition}

Blueprint for a font provider that converts normalized font requests into CSS import URLs.

| Property | Type | Description | Default |
|---|---|---|---|
| `buildImportUrls?` | `(fonts: readonly FontsProviderFontEntry[], context: FontsProviderContext) => string \| string[] \| null \| undefined` | Generates one or more CSS import URLs for the given font entries. | `undefined` |

**Remarks:**

Register custom providers via `FontsPluginOptions.providers` using `defineFontsProvider`. Each font entry carries its fully resolved `providerOptions`; the context contains only provider-wide values that are identical for every entry in the callback.

```ts
const myProvider: FontsProviderDefinition = {
  buildImportUrls(fonts, ctx) {
    return fonts.map(f => `https://my-cdn.com/css?family=${f.name}`)
  },
}
```

### FontsProviderFontEntry {#interface-fontsproviderfontentry}

Describes a single font family to be loaded by a provider.

| Property | Type | Description | Default |
|---|---|---|---|
| `name` | `string` | Font family name as recognized by the provider (e.g. `'Roboto'`). | — |
| `weights` | `string[]` | Font weight values to load (e.g. `['400', '700']`). | — |
| `italic` | `boolean` | Whether to include italic variants for the requested weights. | — |
| `providerOptions` | `EffectiveFontsProviderOptions` | Active effective provider options after defaults, overrides, and nullish deletion markers are resolved. | — |

**Remarks:**

Constructed internally by normalizing user-supplied font entries. `providerOptions` is the active effective map after global defaults and per-font overrides have been resolved; nullish deletion markers are removed before provider execution.

```ts
const entry: FontsProviderFontEntry = {
  name: 'Roboto',
  weights: ['400', '700'],
  italic: true,
  providerOptions: { text: 'Hello' },
}
```

### FontsProviderOptions {#type-fontsprovideroptions}

Config-time provider option map.

**Type:** `Partial<Record<string, FontsProviderOptionValue | null>>`

**Remarks:**

`null` and `undefined` are deletion markers: after global defaults and per-font overrides are resolved, nullish keys are absent from the effective map passed to providers.

### FontsProviderOptionValue {#type-fontsprovideroptionvalue}

Accepted active values for a single font-provider option.

**Type:** `string | number | boolean | Array<string | number | boolean>`

**Remarks:**

Arrays are serialized as comma-separated values by the built-in stylesheet providers.

## Module augmentations

### EngineConfig (@pikacss/core) {#augmentation-engineconfig-pikacss-core}

| Property | Type | Description | Default |
|---|---|---|---|
| `fonts?` | `FontsPluginOptions` | Configuration for the fonts plugin. | `undefined` |

## Next

* [Fonts plugin](/official-plugins/fonts)
* [Plugin Typography API reference](/api/plugin-typography)
* [API reference overview](/api/)