# extendVars

Override, add, or remove values in an existing variable set.

An extension shares the base set's references, so styles written against the base read the extension's values inside its scope. Pass both sets to [`defineConfig`](/docs/api/core/defineConfig) as named alternatives. Named alternatives must keep the default set's paths, so add new values to the default set and override them in the others.

```ts title="zyzz.config.ts"
import { defineConfig, defineVars, extendVars } from 'zyzz'

const base = defineVars({
  color: { accent: '#2563eb' },
  spacing: { page: '1rem' },
})

const brand = extendVars(base, { color: { accent: '#9333ea' } })

export const { style, vars } = defineConfig({
  defaultVars: 'base',
  vars: { base, brand },
})
```

`extendVars` is the root alias of `Vars.extend`, with the same types and behavior.

## Signature

```ts
// A set with some values replaced, added, or removed
extendVars(base, values)
// Derived values computed from the extended set
extendVars(base, values, derive)
// A new set with its own variables, linked to the base's
extendVars(base, values, derive?, { id })
```

## Parameters

### base

* **Type:** `Vars.Definition`

The set to extend, from [`defineVars`](/docs/api/core/defineVars), another extension, or the `vars` returned by [`defineConfig`](/docs/api/core/defineConfig).

```ts
const brand = extendVars(base, { color: { accent: '#9333ea' } })
```

### values

* **Type:** `Vars.Changes`

Replacement values at existing paths, new values at new paths, and `null` at paths to remove. Restating a base reference at its own path, such as `base.spacing.page` at `spacing.page`, keeps the base value. Each override replaces a whole leaf, including conditional values and color pairs, and omitted paths keep their base values. Derived values in the base follow the overrides they reference.

```ts
import { defineVars, extendVars } from 'zyzz'

const base = defineVars({ color: { palette: { ink: '#171717' } } }, (vars) => ({
  color: { text: vars.color.palette.ink },
}))

// `color.text` also becomes blue inside this set's scope
const blue = extendVars(base, { color: { palette: { ink: '#2563eb' } } })
```

### derive

* **Type:** `(vars: Vars.References<values>) => Vars.Values`

Optional values computed from the extended set's references, such as typography presets. Derived values can only add paths.

### options.id

* **Type:** `string`

Makes the extension a new set with its own variables instead of an alternative to the base. Its inherited values reference the base's variables, so they stay linked, and its overrides and additions use its own names. Inherited values emit no CSS of their own unless another set with the same identity overrides them. Use it to build one set on another, such as a surface on shared primitives, and omit it for alternatives like a dark or brand set.

## Remove Paths

`null` at an existing path removes it from the extension. A leaf leaves the set's references, its `style` tokens, and its emitted CSS. A category removes every leaf below it, including typography presets.

```ts title="zyzz.config.ts"
import { defineConfig, extendVars } from 'zyzz'
import { vars as base } from 'zyzz/default'

// `radius.3xl`, `radius.4xl`, and every `shadow` token are gone
const site = extendVars(
  base,
  { radius: { '3xl': null, '4xl': null }, shadow: null },
  { id: 'site/vars' },
)

export const { style } = defineConfig({ id: 'site', vars: site })
```

With `options.id`, the remaining values still reference the base's variables, so a remaining base value can read a removed one. Without it, the extension shares the base's variables, and a remaining value that references a removed path throws `Vars.InvalidError`. Named alternatives in [`defineConfig`](/docs/api/core/defineConfig) must keep the default set's paths, so remove paths from the default set rather than from an alternative.

## Extend a package config

A package can export the `vars` of its config. Extend them to author with the package's tokens and your own.

```ts title="zyzz.config.ts"
import { defineConfig, defineVars, extendVars } from 'zyzz'

// Usually imported, such as `import { vars as site } from 'design-system'`
const { vars: site } = defineConfig({
  id: 'site',
  vars: defineVars({ spacing: { page: '24px' } }),
})

const app = extendVars(
  site,
  { spacing: { gutter: '20px' } },
  { id: 'app/vars' },
)

export const { style, vars } = defineConfig({ id: 'app', vars: app })
```

## Returns

### set

* **Type:** `Vars.Definition<values>`

A set with the base set's paths and references, plus added paths and minus removed ones. Select it with [`vars`](/docs/api/core/defineConfig/vars) for a subtree, or with [`appearance`](/docs/api/core/defineConfig/appearance) for the document.

```tsx
// Elements inside read the brand accent
<section {...vars({ set: 'brand' })} />
```

## Errors

TypeScript rejects values outside a path's type, additions that replace a category with a value or a value with a category, and `null` at a path the base lacks. At runtime, the same input throws `Vars.InvalidError` with the path of the invalid value.

```ts
import { defineVars, extendVars } from 'zyzz'

const base = defineVars({ spacing: { page: '1rem' } })

// Overrides keep the path's value type
extendVars(base, { spacing: { page: '#ffffff' } })
// error: Type '"#ffffff"' is not assignable to type '"#ffffff" & (Conditional<Length | Reference<"spacing"> | Composition<"spacing">> | null)'.
```

An override that creates a reference cycle, a derived value at an existing path, or a derived `null` also throws `Vars.InvalidError`.

## React Native

Native compilation resolves each set to native values, and selecting a set switches the values views receive. Overrides follow the same native limits as [`defineVars`](/docs/api/core/defineVars#react-native).

```ts title="tokens.ts"
import { defineVars, extendVars } from 'zyzz'

const base = defineVars({ spacing: { page: '16px' } })

// A roomier set for larger screens, selected by the app
export const roomy = extendVars(base, { spacing: { page: '24px' } })
```
