# viewTransition

Emit an `@view-transition` rule that opts documents into cross-document transitions.

`viewTransition` emits its descriptors into the shared stylesheet. The browser runs the transitions on matching same-origin navigations, so only target browsers that support the rule animate.

```ts title="src/transitions.ts"
import { viewTransition } from 'zyzz/web'

// Emits `@view-transition{navigation:auto;}`
viewTransition({ navigation: 'auto' })
```

## Signature

```ts
// Navigation and transition type descriptors
viewTransition(descriptors)
```

## Parameters

### descriptors.navigation

* **Type:** `'auto' | 'none'`
* **Default:** `undefined`

Whether same-origin navigations to or from the document run a view transition.

```ts
// Disables transitions for this document
viewTransition({ navigation: 'none' })
```

### descriptors.types

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

A space-separated list of custom identifiers, or `none`. Transition types activate `:active-view-transition-type()` selectors during the transition.

```ts
import { viewTransition } from 'zyzz/web'

viewTransition({
  navigation: 'auto',
  // Matches `:active-view-transition-type(slide)`
  types: 'slide forward',
})
```

### descriptors\[atRule]

* **Type:** `` '@layer' | `@${'container' | 'layer' | 'media' | 'supports'}${' ' | '\t' | '\n' | '\r' | '\f' | '(' | `/*${string}*/`}${string}` ``

Grouping keys around a complete set of descriptors. Each value holds a complete definition or further grouping keys, and outer keys emit outer groups. A bare `@layer` key emits an anonymous layer.

```ts
import { viewTransition } from 'zyzz/web'

viewTransition({
  // Skips navigation transitions under reduced motion
  '@media (prefers-reduced-motion: no-preference)': { navigation: 'auto' },
})
```

## Returns

`void`. The compiler erases the call and keeps the rule in the shared stylesheet. Vite, Unplugin, and `zyzz/node` scan the source tree, so unimported modules still contribute. Next.js compiles only imported modules, so import the declaring module from an entrypoint there.

## Types

* **`viewTransition.Options`:** The accepted descriptors.

```ts
import type { viewTransition } from 'zyzz/web'

// Reads the accepted navigation keywords
type Navigation = viewTransition.Options['navigation']
```

## Errors

TypeScript rejects unknown descriptors, invalid `navigation` keywords, and reserved names in `types`.

```ts
import { viewTransition } from 'zyzz/web'

// The keywords are `auto` and `none`
viewTransition({ navigation: 'always' })
// error: Type 'string' is not assignable to type 'never'.
```

The compiler reports `Source.ExtractError` for values it cannot read statically. Native builds reject the call with `Native.CompileError`.