# motion/swap (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/motion/swap.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx).

## Components

### `Crossfade`

Component.

Swaps content by key with a cross-fade: the previous node stays in the
same grid cell for the exit (`readExitMs()`) playing its exit while the new
one plays its enter; with motion off it is replaced at once. `children ===
null` is a valid state (empty slot).

```ts
function Crossfade(props: CrossfadeProps): Element
```

**Parameters**

- `props` (`CrossfadeProps`): Component props.

**Returns** `Element`

**Props**

- `activeKey` (`string | number`): Identity of the current content; a change triggers the swap.
- `align?` (`'start' | 'end'`): `text` only: which edge both lines hold to. `end` for text set against
  something on its right (a trailing slot): when the outgoing line leaves
  and the cell narrows, the line on show stays where it is.
- `children` (`ReactNode`): The current content. `null` is a valid empty slot.
- `className?` (`string`): Extra classes on the wrapping cell.
- `settle?` (`boolean`): For content inside something that is itself still appearing (a line
  fading in): a key change in its first moments replaces the content
  without a crossfade, since two lines fading over each other inside a
  line that is fading in reads as a flicker.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `variant?` (`'text' | 'scale'`): `scale` (default): the glyph swap, in/out through scale around the
  centre; right for spinners, checks and icons. `text`: for a line of
  words, anchored left; the old line blurs away, the new one sharpens
  into place, no scale.

Source: [ui/src/motion/swap.tsx:111](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx#L111)

### `Presence`

Component.

Keeps `children` mounted for the exit (`readExitMs()`) after `show` flips
false so the exit animation plays. Renders nothing once the exit is done.

```ts
function Presence(props: PresenceProps): Element | null
```

**Parameters**

- `props` (`PresenceProps`): Component props.

**Returns** `Element | null`

**Props**

- `children` (`ReactNode`): The content to show and animate out.
- `className?` (`string`): Extra classes on the wrapper (sizing, spacing).
- `display?` (`'inline' | 'block'`): Inline wrapper by default; `block` for full-width rows.
- `show` (`boolean`): Whether the content is shown. When it turns false, the content stays mounted for its exit.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `variant?` (`'text' | 'scale'`): `scale` (default) for glyphs; `text` blurs a line of words in and out, anchored left.

Source: [ui/src/motion/swap.tsx:47](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx#L47)

## Functions

### `useCadencedValue`

Function.

Hold a fast-changing value to a readable cadence: at most one change every
`ms`, the newest value always wins, and the last one always lands (a
trailing update fires when the source goes quiet). The first value shows
at once.

```ts
function useCadencedValue<T>(value: T, ms: number): T
```

**Type parameters**

- `T`

**Parameters**

- `value` (`T`): The source value, which may change faster than it should show.
- `ms` (`number`): The minimum time between shown changes, in ms.

**Returns** `T`: The value to show.

Source: [ui/src/motion/swap.tsx:188](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx#L188)

## Interfaces

### `CrossfadeProps`

Interface.

Props for [`Crossfade`](https://zidane.si/docs/reference/ui-motion-swap.md#Crossfade).

```ts
interface CrossfadeProps
```

**Properties**

- `activeKey` (`string | number`): Identity of the current content; a change triggers the swap.
- `align?` (`'start' | 'end'`): `text` only: which edge both lines hold to. `end` for text set against
  something on its right (a trailing slot): when the outgoing line leaves
  and the cell narrows, the line on show stays where it is.
- `children` (`ReactNode`): The current content. `null` is a valid empty slot.
- `className?` (`string`): Extra classes on the wrapping cell.
- `settle?` (`boolean`): For content inside something that is itself still appearing (a line
  fading in): a key change in its first moments replaces the content
  without a crossfade, since two lines fading over each other inside a
  line that is fading in reads as a flicker.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `variant?` (`'text' | 'scale'`): `scale` (default): the glyph swap, in/out through scale around the
  centre; right for spinners, checks and icons. `text`: for a line of
  words, anchored left; the old line blurs away, the new one sharpens
  into place, no scale.

Source: [ui/src/motion/swap.tsx:72](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx#L72)

### `PresenceProps`

Interface.

Props for [`Presence`](https://zidane.si/docs/reference/ui-motion-swap.md#Presence).

```ts
interface PresenceProps
```

**Properties**

- `children` (`ReactNode`): The content to show and animate out.
- `className?` (`string`): Extra classes on the wrapper (sizing, spacing).
- `display?` (`'inline' | 'block'`): Inline wrapper by default; `block` for full-width rows.
- `show` (`boolean`): Whether the content is shown. When it turns false, the content stays mounted for its exit.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.
- `variant?` (`'text' | 'scale'`): `scale` (default) for glyphs; `text` blurs a line of words in and out, anchored left.

Source: [ui/src/motion/swap.tsx:26](https://github.com/Tahul/zidane/blob/main/ui/src/motion/swap.tsx#L26)