Plugin Fonts API reference

Source information

• 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 when you need conceptual usage guidance instead of exact symbol lookup.

Functions

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.

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

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.

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

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

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

Types

EffectiveFontsProviderOptions

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

Type: Partial<Record<string, FontsProviderOptionValue>>

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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

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)

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

Next

• Fonts plugin
• Plugin Typography API reference
• API reference overview