API Reference

Complete reference for the kinetic chain factory, component props, hooks, presets, and types.

kinetic(tag)

The single public factory. Returns a renderable React component with chain methods attached.

function kinetic<Tag extends ElementType>(tag: Tag): KineticComponent<Tag, 'transition'>

Argument	Type	Description
`tag`	`ElementType`	HTML tag name (`'div'`, `'section'`, …) or any React component that forwards refs.

The returned component is a KineticComponent<Tag, Mode> — a React FC with chain methods (.preset, .enter, .collapse, .group, …). Default mode: 'transition'.

import { kinetic, fade } from '@vitus-labs/kinetic'

// Default transition mode
const FadeDiv = kinetic('div').preset(fade)

// Switch modes via chain
const Accordion = kinetic('div').collapse()
const StaggerList = kinetic('ul').preset(slideUp).stagger({ interval: 50 })
const AnimatedList = kinetic('ul').preset(fade).group()

All chain methods return a new component instance (immutable) — re-chain to extend or override.

Spread a preset's style and class props onto the component. Equivalent to calling .enter(), .enterTo(), .enterTransition(), .leave(), .leaveTo(), .leaveTransition() (and/or the class equivalents) with the preset's values.

.preset(preset: StyleTransitionProps & ClassTransitionProps): KineticComponent<Tag, Mode>

Use built-in presets (fade, slideUp, scaleIn, …) or any object matching the shape.

`.enter(styles)` / `.enterTo(styles)` / `.enterTransition(value)`

Style-based enter definition.

.enter(styles: CSSProperties)             // Initial styles applied at enter start
.enterTo(styles: CSSProperties)           // End styles applied on next animation frame
.enterTransition(value: string)           // CSS transition shorthand for enter

`.leave(styles)` / `.leaveTo(styles)` / `.leaveTransition(value)`

Mirror of the enter triplet, for the leave phase.

.leave(styles: CSSProperties)
.leaveTo(styles: CSSProperties)
.leaveTransition(value: string)

`.enterClass(opts)` / `.leaveClass(opts)`

Class-based animation definition. Compatible with Tailwind, CSS modules, or any class-based system.

.enterClass({ active?: string, from?: string, to?: string })
.leaveClass({ active?: string, from?: string, to?: string })

Field	Maps to internal prop	Lifecycle
`active`	`enter` / `leave`	Applied during the entire phase
`from`	`enterFrom` / `leaveFrom`	Applied on first frame, removed on next
`to`	`enterTo` / `leaveTo`	Applied on second frame, kept until complete

`.config(opts)`

Configure mode-agnostic and mode-specific defaults. The accepted shape narrows based on the current mode.

// Transition mode (default)
.config({ appear?: boolean; unmount?: boolean; timeout?: number })

// Collapse mode
.config({ appear?: boolean; timeout?: number; transition?: string })

// Stagger mode
.config({ appear?: boolean; timeout?: number; interval?: number; reverseLeave?: boolean })

// Group mode
.config({ appear?: boolean; timeout?: number })

Field	Default	Modes	Description
`appear`	`false`	all	Animate the initial mount as if `show` flipped to `true`
`unmount`	`true`	transition	When `false`, hide with `display: none` instead of removing from DOM
`timeout`	`5000`	all	Safety timeout (ms) — completes the transition if `transitionend` never fires
`transition`	`'height 300ms ease'`	collapse	CSS transition shorthand applied to the height animation
`interval`	`50`	stagger	Delay (ms) between each child's animation start
`reverseLeave`	`false`	stagger	Reverse stagger order on leave

`.on(callbacks)`

Set component-level default lifecycle callbacks. Per-render props override these.

.on({
  onEnter?: () => void
  onAfterEnter?: () => void
  onLeave?: () => void
  onAfterLeave?: () => void
})

`.collapse(opts?)` / `.stagger(opts?)` / `.group()`

Switch the component into a different mode. Returns a KineticComponent<Tag, NewMode> — the prop shape narrows accordingly.

.collapse(opts?: { transition?: string; appear?: boolean; timeout?: number }): KineticComponent<Tag, 'collapse'>
.stagger(opts?: { interval?: number; reverseLeave?: boolean; appear?: boolean; timeout?: number }): KineticComponent<Tag, 'stagger'>
.group(): KineticComponent<Tag, 'group'>

Mode switching is final for that link of the chain — the returned component reflects the new mode and accepts only that mode's props.

Component Props

The rendered component's prop shape depends on its mode. Below is the full per-mode prop list. All shapes also include the chosen tag's HTML attributes (e.g. className, onClick, id).

Transition mode

type KineticTransitionProps<Tag> = HTMLAttrsOf<Tag> & {
  show: boolean
  appear?: boolean
  unmount?: boolean
  timeout?: number
  children?: ReactNode
} & Partial<TransitionCallbacks>

Prop	Type	Default	Description
`show`	`boolean`	—	`true` runs enter, `false` runs leave + unmount
`appear`	`boolean`	`false`	Animate on initial mount
`unmount`	`boolean`	`true`	Unmount on leave; if `false`, keep with `display: none`
`timeout`	`number`	`5000`	Safety timeout (ms)
`children`	`ReactNode`	—	Single rendered element

Collapse mode

type KineticCollapseProps<Tag> = HTMLAttrsOf<Tag> & {
  show: boolean
  appear?: boolean
  timeout?: number
  transition?: string
  children?: ReactNode
} & Partial<TransitionCallbacks>

Prop	Type	Default	Description
`show`	`boolean`	—	`true` expands, `false` collapses
`appear`	`boolean`	`false`	Animate the collapse on initial mount
`timeout`	`number`	`5000`	Safety timeout (ms)
`transition`	`string`	`'height 300ms ease'`	CSS transition shorthand for the height animation
`children`	`ReactNode`	—	Content whose `scrollHeight` is measured

Stagger mode

type KineticStaggerProps<Tag> = HTMLAttrsOf<Tag> & {
  show: boolean
  appear?: boolean
  timeout?: number
  interval?: number
  reverseLeave?: boolean
  children: ReactElement | ReactElement[]
} & Partial<TransitionCallbacks>

Prop	Type	Default	Description
`show`	`boolean`	—	Controls visibility of all children
`appear`	`boolean`	`false`	Animate on initial mount
`timeout`	`number`	`5000`	Safety timeout (ms)
`interval`	`number`	`50`	Delay (ms) between each child's animation start
`reverseLeave`	`boolean`	`false`	Reverse stagger order on leave
`children`	`ReactElement[] \| ReactElement`	—	Children to stagger (must have stable keys)

Group mode

type KineticGroupProps<Tag> = HTMLAttrsOf<Tag> & {
  appear?: boolean
  timeout?: number
  children: ReactElement | ReactElement[]
} & Partial<TransitionCallbacks>

Prop	Type	Default	Description
`appear`	`boolean`	`false`	Animate the initial children on mount
`timeout`	`number`	`5000`	Safety timeout (ms)
`children`	`ReactElement[] \| ReactElement`	—	Keyed children — adding triggers enter, removing triggers leave

There is no show prop in group mode — visibility is driven entirely by which children are present in the array.

Lifecycle Callbacks

type TransitionCallbacks = {
  onEnter?: () => void
  onAfterEnter?: () => void
  onLeave?: () => void
  onAfterLeave?: () => void
}

Callback	When it fires
`onEnter`	Enter phase begins (start styles applied)
`onAfterEnter`	Enter animation completes (browser fires `transitionend` or safety timeout)
`onLeave`	Leave phase begins
`onAfterLeave`	Leave animation completes — fires immediately before unmount

Callbacks set via .on() are component-level defaults; per-instance props on the rendered component override them.

In prefers-reduced-motion: reduce mode, the visible animation is skipped but callbacks still fire so analytics and focus-management side-effects remain consistent.

Animation Prop Shapes

Used internally by the chain methods and exported as types.

`StyleTransitionProps`

type StyleTransitionProps = {
  enterStyle?: CSSProperties
  enterToStyle?: CSSProperties
  enterTransition?: string
  leaveStyle?: CSSProperties
  leaveToStyle?: CSSProperties
  leaveTransition?: string
}

`ClassTransitionProps`

type ClassTransitionProps = {
  enter?: string
  enterFrom?: string
  enterTo?: string
  leave?: string
  leaveFrom?: string
  leaveTo?: string
}

`TransitionStage`

type TransitionStage = 'hidden' | 'entering' | 'entered' | 'leaving'

Built-in Presets

Six presets ship in the core package. Each is a Preset (StyleTransitionProps & ClassTransitionProps).

import {
  fade,
  scaleIn,
  slideUp,
  slideDown,
  slideLeft,
  slideRight,
} from '@vitus-labs/kinetic'

Preset	Effect
`fade`	Opacity 0 → 1 on enter, reverse on leave
`scaleIn`	Scale + opacity, slight zoom-in feel
`slideUp`	Translate from below + fade
`slideDown`	Translate from above + fade
`slideLeft`	Translate from right + fade
`slideRight`	Translate from left + fade

For 122 additional presets, factory generators, and composition utilities, see @vitus-labs/kinetic-presets.

Hooks

`useTransitionState`

The state machine that powers transition mode. Drive enter / leave manually for cases the chain factory doesn't cover.

import { useTransitionState } from '@vitus-labs/kinetic'

const { stage, ref, shouldMount, complete } = useTransitionState({
  show,
  appear: false,
  timeout: 5000,
})

Returns:

Field	Type	Description
`stage`	`TransitionStage`	Current lifecycle stage
`ref`	`RefObject<HTMLElement \| null>`	Attach to the element you're animating
`shouldMount`	`boolean`	Whether to render the element at all
`complete`	`() => void`	Call to advance to the next stage when the animation finishes

`useAnimationEnd`

Detect transitionend / animationend with a safety timeout fallback. Ignores bubbled events from children.

import { useAnimationEnd } from '@vitus-labs/kinetic'

useAnimationEnd(elementRef, () => onComplete(), {
  timeout: 5000,
  active: stage === 'entering' || stage === 'leaving',
})

TransitionStateResult

Returned shape from useTransitionState:

type TransitionStateResult = {
  stage: TransitionStage
  ref: RefObject<HTMLElement | null>
  shouldMount: boolean
  complete: () => void
}

Exports

import {
  // Factory
  kinetic,
  // Presets
  presets,
  fade,
  scaleIn,
  slideUp,
  slideDown,
  slideLeft,
  slideRight,
  // Hooks
  useTransitionState,
  useAnimationEnd,
} from '@vitus-labs/kinetic'

import type {
  KineticComponent,
  Preset,
  ClassTransitionProps,
  StyleTransitionProps,
  TransitionCallbacks,
  TransitionStage,
  TransitionStateResult,
  UseTransitionState,
  UseAnimationEnd,
} from '@vitus-labs/kinetic'