# style

Define a callable style that compiles to static CSS and returns styling props.

The compiler reads each definition at build time, emits its rules, and rewrites the definition into a function that returns class names. Applying it never creates CSS.

```tsx title="Card.tsx"
import { style } from 'zyzz'

export function Card(props: Card.Props) {
  return (
    // Spread each applied definition onto its element
    <article {...styles.card()}>
      <h2 {...styles.title()}>{props.title}</h2>
    </article>
  )
}

export declare namespace Card {
  type Props = { title: string }
}

namespace styles {
  export const card = style({ borderRadius: '8px', padding: '16px' })

  export const title = style({ fontSize: '1.25rem', margin: 0 })
}
```

## Signature

```ts
// Static declarations
style(styles?, options?)

// Declarations that read values passed on each call
style((values) => styles, options?)

// Earlier definitions and literal objects composed in order
style([definition, styles], options?)
```

Each form returns a definition, which is applied by calling it. The `style` returned by [`defineConfig`](/docs/api/core/defineConfig) has the same signature and also accepts the config's token names.

## Parameters

### styles

* **Type:** `Style.LiteralProperties | ((values: values) => Style.LiteralProperties) | readonly (style.ReturnType | Style.LiteralProperties)[]`
* **Default:** `{}`

CSS declarations keyed by camelCase property names, in authored order. [Values](/docs/api/core/values) lists the supported properties and literal values.

```ts
import { style } from 'zyzz'

const card = style({
  // The suffix marks the declaration as important
  color: 'black !important',
  // Arrays emit fallbacks in order
  display: ['block', 'grid'],
  padding: '16px',
})
```

Pseudo-class, pseudo-element, and at-rule keys nest declarations at any depth, keeping the authored selector's specificity. The [Conditions](/docs/guides/conditions) guide covers query aliases and container queries.

```ts
import { style } from 'zyzz'

const link = style({
  color: 'blue',
  // Pseudo-classes and pseudo-elements target the styled element
  ':hover': { color: 'navy' },
  // At-rules require a complete query
  '@media (width >= 48rem)': { fontSize: '1.125rem' },
})
```

A callback receives one parameter with an explicit object type whose fields are strings or numbers. Its object body compiles to static rules that read each value through a private custom property.

```ts
import { style } from 'zyzz'

// Each call supplies `amount`, without creating CSS
const meter = style((values: { amount: `${number}%` }) => ({
  backgroundColor: 'green',
  width: values.amount,
}))
```

An array composes static definitions and literal objects into one definition with its own rules. Entries apply in order, so later declarations override earlier ones within matching conditions. Each entry must be declared earlier in the module or imported.

```ts
import { style } from 'zyzz'

const button = style({ color: 'black', padding: '8px 16px' })

// Copies the button declarations, then overrides the color
const primary = style([button, { color: 'white' }])
```

On React Native, entries must use the composing style's variable catalog, so Provider selections resolve each copied token. Without a compiler transform, a composition that includes a definition from a compiled package requires `options.id`, because compiled definitions carry only their class names.

### styles.selectors

* **Type:** `{ [selector: string]: Style.LiteralProperties }`

Selector strings mapped to nested declarations. `&` marks the styled element, and every branch of a selector list requires it. Template keys interpolate an earlier definition, which styles one element by the state of another.

```ts
import { style } from 'zyzz'

namespace styles {
  // An empty definition supplies a selector identity
  export const card = style()

  export const label = style({
    color: 'gray',
    selectors: {
      '[data-state="open"] &': { color: 'blue' },
      [`${card}:hover &`]: { color: 'black' },
    },
  })
}
```

Specificity follows the authored selector, so wrap a selector in `:where()` to lower it. Express state through data and ARIA attributes. Callback values apply only in selectors that target the styled element, since their private custom properties live on it.

Template keys apply only inside `selectors`, so top-level keys remain declarations, pseudo keys, and at-rules. An interpolation names an earlier definition directly, as `${card}`, or through its namespace, as `${styles.card}`.

### styles.vars

* **Type:** ``{ [variable: `--${string}`]: string | number }``

Static assignments for variables declared with [`variable`](/docs/api/core/variable), keyed by computed reference. Assignments can also appear inside conditions and selectors.

```ts
import { style, variable } from 'zyzz'

namespace variables {
  export const accent = variable('color')
}

const button = style({
  backgroundColor: variables.accent,
  // Assigns the variable on the styled element
  vars: { [variables.accent]: 'royalblue' },
  ':hover': { vars: { [variables.accent]: 'navy' } },
})
```

Computed keys lose each variable's value type in TypeScript.

### styles.targets

* **Type:** `Style.TargetBranches`

Platform branches applied after the shared declarations. Web output reads `targets.web`. Native output reads `targets.native`, then `targets.ios` or `targets.android` for the build platform.

```ts
import { style } from 'zyzz'

const balance = style({
  fontSize: '16px',
  // Branch values apply only on their platform
  targets: {
    native: { fontVariant: ['tabular-nums'] },
    web: { fontVariantNumeric: 'tabular-nums' },
  },
})
```

Callback definitions cannot contain target branches. Native branches use React Native property names and values. [Native Styling](/docs/guides/native/styling) covers platform branches in detail.

### options.id

* **Type:** `string`
* **Default:** `undefined`

A fixed definition identity, which replaces the identity derived from the declarations. Empty and callback definitions require it when source runs without a compiler transform, such as in tests that compile extracted styles directly.

```ts
import { style } from 'zyzz'

// Applies as `z-style-id-card` without a compiler transform
const card = style({}, { id: 'card' })
```

## Application

Applying a definition returns props for one element. The optional argument accepts only styling overrides, so event handlers, children, and ARIA attributes stay on the element.

A callback definition also requires every declared value on each call. Each call assigns the values to private custom properties without creating CSS. A call spread alone onto an element writes a value that fills one unconditional declaration to that property inline, unless its type admits a CSS-wide keyword, as `string` does.

```ts
// Width becomes 50% on this element
styles.meter({ amount: '50%' })
```

### options.className

* **Type:** `string`
* **Default:** `undefined`

Classes appended after the generated classes. Their position in the string does not change precedence, which follows the order of the emitted rules.

```ts
// Returns the generated classes followed by `external`
styles.card({ className: 'external' })
```

### options.style

* **Type:** `style.Options['style']`
* **Default:** `undefined`

Inline declarations copied onto the returned `style`. React output accepts strings and numbers. HTML output requires CSS values with units. Inline values are not resolved as tokens or validated at runtime.

```ts
// Overrides the compiled padding on this element only
styles.card({ style: { padding: '24px' } })
```

### options.vars

* **Type:** ``{ [variable: `--${string}`]: string | number | undefined }``
* **Default:** `undefined`

Inline custom-property assignments keyed by variable reference. They merge into the returned `style` before `options.style`. An `undefined` value omits the assignment, and callback values keep precedence over assignments to their private properties.

```ts
// Overrides the static assignment on this element
styles.button({ vars: { [variables.accent]: 'crimson' } })
```

## Returns

### className

* **Type:** `string`

The generated classes, followed by `options.className` when supplied.

```tsx
// Spreading assigns `className` and `style` together
<article {...styles.card()} />
```

### style

* **Type:** `Readonly<Record<string, string | number | undefined>> | undefined`

Inline custom properties and overrides, present only when the call assigns one. Configurations with `output: 'html'` return `class` and a serialized `style` string instead.

```ts
// { className: '…', style: { '--…': '50%' } }
const props = styles.meter({ amount: '50%' })
```

## Types

* **`style.Composable<entry>`:** Accepts a static definition as a composition entry.
* **`style.DefinitionOptions`:** The definition's second argument, `{ id? }`.
* **`style.Dynamic<values>`:** A callback definition, which requires `values` on each call.
* **`style.Options`:** The styling overrides accepted when applying a definition.
* **`style.Props`:** The returned props, `className` and an optional `style`.
* **`style.ReturnType`:** A static definition, called with optional overrides.

```tsx title="Panel.tsx"
import type { ReactNode } from 'react'
import { style } from 'zyzz'

export function Panel(props: Panel.Props) {
  // Forwards caller overrides to the definition
  return <section {...styles.panel(props.overrides)}>{props.children}</section>
}

export declare namespace Panel {
  type Props = { children: ReactNode; overrides?: style.Options | undefined }
}

namespace styles {
  export const panel = style({ padding: '16px' })
}
```

## Errors

TypeScript rejects unsupported properties and values in definitions, and unknown keys when applying one.

```ts
import { style } from 'zyzz'

const button = style({ padding: '8px 16px' })

// Event handlers belong on the element
button({ onClick: () => {} })
// error: Object literal may only specify known properties, and 'onClick' does not exist in type 'Options<"react"> & Record<never, never>'.
```

The compiler reports unsupported source as `Source.ExtractError` with the source location, such as a selector without `&` or a composition entry that is a variants or callback definition. Without a compiler transform, an empty or callback definition without `options.id` throws an `Error`, and such a composition entry throws `Style.InvalidError`.

## React Native

Applying a definition on native returns `{ style }` with compiled style objects instead of class names. Declarations that native views cannot express fail native compilation with a diagnostic.

```tsx title="Profile.tsx"
import { Text } from 'react-native'
import { style } from 'zyzz'

export function Profile() {
  // Spreads a native `style` prop
  return <Text {...styles.name()}>Ada</Text>
}

namespace styles {
  export const name = style({ color: '#111111', fontSize: '16px' })
}
```

[Native Styling](/docs/guides/native/styling) covers units, fonts, and dynamic values on native, and [Values](/docs/api/react-native/values) lists the supported subset.
