JavaScript API · Kinesis

Starting Kinesis

initKinesis(options?)

Sets up every [data-kinesis] element and keeps watching the page for new ones, removed ones, theme changes, and new stylesheets. Calling it again returns the same app and refreshes it. Does nothing on the server.

initKinesis(options?: KinesisOptions): { refresh(): void; destroy(): void }

createKinesis(root, options?)

Makes root a scope (adding data-kinesis if needed) and returns controls for it.

createKinesis(root: Element | string, options?: KinesisOptions): {
  root: Element
  target(element: Element, props?: KinesisProps): KinesisTarget
  refresh(): void   // re-read CSS
  pause(): void
  resume(): void
  destroy(): void   // restore every style Kinesis wrote
}

configure(options)

interface KinesisOptions {
  reducedMotion?: "user" | "always" | "never"   // default "user"
  debug?: boolean                               // console diagnostics, default false
}

refresh()

Re-reads CSS in every scope. Only needed after changes Kinesis can't observe. See Working with CSS.

requestOrientation()

Asks for device-orientation access. Call it from a click. If granted, device tilt drives parallax and tilt on touch devices. Resolves to true or false.

Animating elements

kinesis(target, props?)

kinesis(element: Element, props?: KinesisProps): KinesisTarget
kinesis(selector: string | Iterable<Element>, props?: KinesisProps): KinesisTargets

KinesisProps has one key per CSS property, in camelCase. Lengths are px, angles deg, times ms.

interface KinesisProps {
  motion?: "instant" | "smooth" | "soft" | "snappy" | "bouncy" | "heavy"
         | [stiffness: number, damping: number, mass?: number]
         | { stiffness: number; damping: number; mass?: number }
  intensity?: number
  perspective?: number
  parallax?: number | [x: number, y: number]
  tilt?: number | [x: number, y: number]
  magnetic?: number
  repel?: number
  follow?: number
  look?: number
  point?: number | null
  spin?: number
  depth?: number
  drag?: "x" | "y" | "both" | null
  when?: "near" | "hover" | "press" | "view" | "view once" | "scroll" | "page" | null
  x?, y?, rotate?, scale?, opacity?, blur?: number | [from: number, to: number]
  color?, background?: string | [from: string, to: string]
  area?: "scope" | "self" | "viewport"
  radius?: number
  limit?: number | null
  axis?: "both" | "x" | "y"
  bounds?: "parent" | "scope" | "viewport" | null
  release?: "throw" | "stay" | "return"
  delay?: number
  stagger?: number
  index?: number
  track?: boolean
}

KinesisTarget

Member	Description
`element`	the element
`set(props)`	set props; they override CSS until reset
`reset(...names)`	return the named props (or all) to CSS
`bind(bindings)`	drive channels or `--custom` properties from signals
`unbind(...names)`	remove the named bindings (or all)
`on(event, fn)`	`"dragstart"`, `"drag"`, or `"dragend"`; returns an unsubscribe function
`progress`	the reaction progress as a signal
`near`	pointer closeness as a signal: 1 at the element's center, 0 at its `radius`
`pointer`	`{ x, y }` signals: the pointer's offset from the element's resting center, px
`destroy()`	remove everything added from JavaScript

Bindable channels: x, y, z, rotate, rotateX, rotateY, scale, opacity, blur, progress, and any --custom-property. Drag events receive { x, y, velocityX, velocityY }.

KinesisTargets (from a selector) has the same methods, applied to every element, plus targets.

Signals

abstract class Signal {
  get(): number
  map(from: [number, number], to: [number, number], options?: { clamp?: boolean }): Signal
  map(fn: (value: number) => number): Signal
  clamp(min: number, max: number): Signal
  spring(motion?: MotionPreset | SpringOptions): Signal
  subscribe(fn: (value: number) => void): () => void
}

Export	Description
`pointer`	`x`, `y`, `nx`, `ny`, `velocityX`, `velocityY`, `speed`, `present`
`scroll`	`x`, `y`, `progress`, `velocity`
`time`	seconds since load; keeps frames running while read
`value(initial)`	a signal you `set()`
`computed(fn)`	a signal derived from others read inside `fn`

Other exports

Export	Description
`presets`	the motion presets as `{ stiffness, damping, mass }`
`properties`	every registered property: `name`, `syntax`, `initial`, `inherits`
`version`	the library version

@amineyarman/kinesis/text

splitText(target: Element | string, by?: "chars" | "words" | "lines"): SplitResult
splitAll(root?: ParentNode): SplitResult[]   // elements with data-k-split

interface SplitResult {
  element: HTMLElement
  chars: HTMLElement[]
  words: HTMLElement[]
  lines: HTMLElement[]
  revert(): void
}

@amineyarman/kinesis/audio

createAudio(
  source: HTMLMediaElement | MediaStream | AudioNode,
  options?: { context?: AudioContext; fftSize?: number; smoothing?: number },
): {
  volume: Signal
  bass: Signal
  mid: Signal
  treble: Signal
  band(fromHz: number, toHz: number): Signal
  context: AudioContext
  resume(): Promise<void>
  destroy(): void
}

@amineyarman/kinesis/vue

Export	Description
`KinesisPlugin`	`app.use(KinesisPlugin, options?)` registers `v-kinesis` and starts discovery (pass `{ auto: false }` to skip)
`vKinesis`	the directive, for local registration

@amineyarman/kinesis/auto

Importing it calls initKinesis() when the document is ready. The <script> build (dist/kinesis.global.js) does the same and exposes everything on window.Kinesis.