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/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. Supports Google Fonts, Bunny Fonts, Fontshare, Coollabs, and custom providers.

import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
  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

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.

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 options for this font, merged with global provider options.	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 CSS @import url(...) rules injected before provider-generated imports.	[]
faces?	FontFaceDefinition[]	Custom @font-face definitions injected as preflight CSS.	[]
display?	string	CSS font-display value applied to all provider-generated imports.	'swap'
providers?	Record<string, FontsProviderDefinition>	Custom font provider implementations keyed by provider name.	{}
providerOptions?	Record<string, FontsProviderOptions>	Provider-level options keyed by provider name, forwarded to buildImportUrls.	{}

Remarks:

Set these under the fonts key in your engine config. The plugin resolves font entries, builds provider import URLs, generates @font-face rules, and 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.

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.	—
options	FontsProviderOptions	Provider-level options merged from providerOptions configuration.	—

Remarks:

Assembled from the resolved plugin configuration during engine setup.

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

FontsProviderDefinition

Blueprint for a font provider that converts font entries 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.

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.	—
options?	FontsProviderOptions	Per-font provider options that override global provider options.	undefined

Remarks:

Constructed internally by normalizing user-supplied font entries. The provider uses these to build CSS import URLs.

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

FontsProviderOptions

Key-value map of provider-specific options passed alongside font requests.

Remarks:

Unsupported option keys are silently ignored by each provider's URL builder.

const opts: FontsProviderOptions = { text: 'Hello' }

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