# font-family

> Applies `font-family` from the named font scale (`sans`, `serif`, `mono`, or an app-extended name) via `var(--ui-font-{name}, fallback)`.

```ts
import { font } from "@sdxc/u/typography";
```

Applies `font-family` from the named font scale (`sans`, `serif`, `mono`,
or an app-extended name) via `var(--ui-font-{name}, fallback)`.
`"inherit"` and `"unset"` pass through unchanged as literal CSS keywords.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.font("serif")` | `css({ fontFamily: "var(--ui-font-serif, ui-serif, Georgia, serif)" })` |
| `u.font("inherit")` | `css({ fontFamily: "inherit" })` |

## Examples

### Basic example

Use `font("sans")`, `font("serif")` or `font("mono")` to set the font family of an element:

```tsx
<div mix={[...]}>
	<div>
		<p mix={[...]}>font("sans")</p>
		<p mix={[font("sans"), text("xl")]}>The quick brown fox jumps over the lazy dog.</p>
	</div>
	<div>
		<p mix={[...]}>font("serif")</p>
		<p mix={[font("serif"), text("xl")]}>The quick brown fox jumps over the lazy dog.</p>
	</div>
	<div>
		<p mix={[...]}>font("mono")</p>
		<p mix={[font("mono"), text("xl")]}>The quick brown fox jumps over the lazy dog.</p>
	</div>
</div>
```

### Inheriting the family

Use `font("inherit")` on a control like a button, which browsers set in their own face, to match the text around it:

```tsx
<p mix={[font("serif"), text("lg")]}>
	Every recipe on this page serves four.{" "}
	<button
		mix={[
			font("inherit"),
			text("lg"),
			p(1, 3),
			rounded("md"),
			bg("brand.tint"),
			fg("brand.emphasis"),
		]}
	>
		Scale for eight
	</button>
</p>
```

## Applying on a state

Wrap the call in a state utility to scope it to one selector.

```ts
u.hover(u.font("serif"))
```

## Responsive design

Wrap the call in a container query to scope it to one width.

```ts
u.at("md", u.font("serif"))
```

## Customizing your theme

### Customizing font families

Redefine a `--ui-font-*` variable to change a family, or declare a new one:

```css
:root {
	--ui-font-display: "Inter Display", ui-sans-serif, system-ui, sans-serif;
}
```

```ts
declare module "@sdxc/u" {
	interface FontFamilies {
		display: true;
	}
}
```

The new name is then accepted wherever the scale is:

```ts
font("display")
```

## Signature

```ts
u.font(name: FontFamilyName | (string & {}))
```