Fonts

@pikacss/plugin-fonts brings hosted fonts, local @font-face definitions, and semantic font tokens into the same build-time workflow as the rest of your PikaCSS configuration.

When to use it

Use the fonts plugin when you want:

provider-driven web font imports without hand-writing URLs
semantic tokens such as sans, mono, and display that become reusable utilities
a single config surface for hosted fonts and local @font-face families
room for provider-specific options and custom provider definitions

Install

pnpmnpmyarn

pnpm add @pikacss/plugin-fonts

npm install @pikacss/plugin-fonts

yarn add @pikacss/plugin-fonts

Minimal setup

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		fonts: {
			sans: 'Roboto:400,500,700',
			mono: ['IBM Plex Mono:400,500', 'ui-monospace'],
		},
	},
})

Each token creates both a font-{token} shortcut and a matching --pk-font-{token} CSS variable.

Provider-specific options

Google Fonts is the default provider, and Bunny, Fontshare, and Coollabs are built in as well.

When a provider needs its own query parameters, pass them through providerOptions instead of hard-coding URL logic into your config.

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		provider: 'coollabs',
		providerOptions: {
			coollabs: {
				text: 'PikaCSS',
			},
		},
		fonts: {
			brand: 'Roboto:400,700',
		},
	},
})

Custom providers

The v2 provider interface lets you register your own import builder while still reusing the same token model and generated utilities.

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { defineFontsProvider, fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		provider: 'acme',
		providerOptions: {
			acme: {
				text: 'PikaCSS',
			},
		},
		providers: {
			acme: defineFontsProvider({
				buildImportUrls(fonts, context) {
					return `https://cdn.example.com/fonts.css?family=${fonts.map(font => font.name).join(',')}&display=${context.display}&text=${context.options.text}&subset=${fonts[0]?.options?.subset}`
				},
			}),
		},
		fonts: {
			brand: {
				name: 'Acme Sans',
				providerOptions: {
					subset: 'latin',
				},
			},
		},
	},
})

Manual `@font-face` and local files

If the font files already live in your project or CDN, define faces and map them into semantic families.

// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { fonts } from '@pikacss/plugin-fonts'

export default defineEngineConfig({
	plugins: [fonts()],
	fonts: {
		faces: [{
			fontFamily: 'Satoshi',
			src: 'url("/fonts/satoshi.woff2") format("woff2")',
			fontWeight: 500,
			fontStyle: 'normal',
			fontDisplay: 'swap',
		}],
		families: {
			display: ['Satoshi', 'sans-serif'],
		},
	},
})

Fonts ​

When to use it ​

Install ​

Minimal setup ​

Provider-specific options ​

Custom providers ​

Manual @font-face and local files ​

Next ​