Enhance an interface from one application boundary.

One boundary, ordinary HTML, optional behaviors.

DYNT is not a component library and does not require every card, button, or section to import an engine. Initialize an engine against an explicit root, provide a selector, and matching elements inside that boundary become managed surfaces.

Choose the smallest package set.

npm install @dynt/formation

npm install @dynt/kinetic

npm install @dynt/formation @dynt/kinetic

npm install @dynt/react @dynt/formation
# or @dynt/kinetic

Import the stylesheet belonging to every installed core engine once at the application entry point or shared layout.

import '@dynt/formation/styles.css';
import '@dynt/kinetic/styles.css';

Start with one root and one selector.

The root may be a Document, DocumentFragment, ShadowRoot, or HTML element. The selector is evaluated only inside that root. Matching the root itself is supported.

const root = document.querySelector('#app');

const kinetic = createKinetic({
  root,
  selector: 'section, article, button, [data-dynt-surface]',
  exclude: '.third-party-widget',
  observe: true
});

Construction is a reversible lifecycle.

Formation can send transient lines from viewport edges, acquire targets in sequence, construct permanent geometry, reveal content, and reverse the same choreography during withdrawal.

import { createFormation } from '@dynt/formation';

const formation = createFormation({
  root: document.querySelector('#app'),
  selector: '[data-dynt-surface]',
  profile: 'line-push',
  observe: true,
  viewportFlow: {
    duration: 1160,
    stagger: 110,
    lineLength: 680,
    overrun: 36
  },
  tokens: {
    duration: 380,
    lineColor: '#ffbf00',
    lineWidth: '1px',
    overflow: 14
  }
});

formation.withdraw();
formation.form();

Lifecycle phases

Subscribe when application logic needs to observe the phase. Do not use fixed timers to guess when construction completed.

const unsubscribe = formation.subscribe(({ element, phase }) => {
  if (phase === 'formed') element.dispatchEvent(new Event('ready'));
});

// Later
unsubscribe();

Built-in profiles

line-push, line-rise, arc-trace, squircle-sweep, chamfer-fold, magnetic-segment, radial-compass, aperture-iris, and elastic-membrane all share the same controller contract.

Separate contact response from waves.

Tilt is pointer-position driven. The near side compresses, the opposite side rises, an opposing shadow reinforces depth, and locally owned content can travel through its own bounded channel. Hovering does not create cell geometry.

import { createKinetic } from '@dynt/kinetic';

const tilt = createKinetic({
  root,
  selector: '[data-tilt-surface]',
  effects: {
    tilt: true,
    content: true,
    wave: false,
    drift: false
  },
  motion: {
    maxTilt: 1.35,
    response: 0.18,
    contentTravel: 3
  }
});

Mark a custom content group with data-dynt-reactor. Kinetic moves the group with CSS translate and leaves the host element's application-owned transform untouched.

Render cell geometry only while a wave is active.

A click or programmatic impact creates a circular front from the real input location. Coherent turbulence bends the front while speed, thickness, recovery, intensity, and growth remain independently configurable.

const wave = createKinetic({
  root,
  selector: '[data-wave-surface]',
  effects: {
    tilt: false,
    content: true,
    wave: true,
    drift: false
  },
  cells: {
    shape: 'hexagon',
    size: [22, 18, 14],
    colorMode: 'gradient',
    colors: ['#143447', '#1686bd', '#8de1ff']
  },
  flow: {
    speed: 1,
    thickness: 1,
    recovery: 1.1,
    intensity: 1.2,
    turbulence: 0.42,
    multi: true,
    maxWaves: 3,
    maxCells: 420
  }
});

Three-level cell sizing

The size tuple is [section, card, nested]. Nested managed surfaces inherit the next level, capped at level three. The site demonstrations use the finer [22, 18, 14] hierarchy so cells remain precise inside cards.

// One target can override the resolved setting.
element.dataset.dyntCellShape = 'circle';
element.dataset.dyntCellSize = '18';

// Or use CSS.
element.style.setProperty('--dynt-cell-size', '18px');

Compose through shared DOM state, not package imports.

Initialize both engines against the same root and selector. Formation owns construction state. Kinetic observes the Formation phase marker, rests while a target is not formed, and resumes input after formation completes.

const options = {
  root: document.querySelector('#app'),
  selector: '[data-dynt-surface]',
  observe: true
};

const formation = createFormation({
  ...options,
  profile: 'line-push',
  viewportFlow: true
});

const kinetic = createKinetic({
  ...options,
  ...kineticPresets.structural,
  cells: { size: [22, 18, 14] }
});

Destroying either controller leaves the other operational. Shared ownership records prevent duplicate decoration and restore application state only after the final owner releases a target.

Scroll loading, route changes, and inserted cards are supported.

Set observe: true when matching elements may appear later. Mutation records are batched. New matches are enhanced, removed elements are restored, and targets that become excluded are released.

const kinetic = createKinetic({
  root,
  selector: '[data-dynt-surface]',
  observe: true
});

// Added later by React, a router, or an IntersectionObserver.
root.append(newSurface);

// Optional explicit reconciliation.
const adopted = kinetic.refresh();

Thin lifecycle helpers, identical engine behavior.

React

import { useRef } from 'react';
import { useKinetic } from '@dynt/react/kinetic';

export function AppShell() {
  const rootRef = useRef<HTMLElement>(null);

  useKinetic({
    rootRef,
    selector: '[data-dynt-surface]',
    observe: true,
    cells: { size: [22, 18, 14] }
  });

  return <main ref={rootRef}>{/* existing tree */}</main>;
}

Use useFormation from @dynt/react/formation for Formation. Memoize object and array configuration when it should remain stable across renders.

Web Components

import { defineKineticElement } from '@dynt/web-components/kinetic';

defineKineticElement('dynt-kinetic-root', {
  selector: '[data-dynt-surface]',
  observe: true
});

<dynt-kinetic-root>
  <article data-dynt-surface>Existing semantic content</article>
</dynt-kinetic-root>

Use CSS channels for dark and light surfaces.

Application themes can provide local line, fill, cell, and surface colors. Keep contrast appropriate for both the surrounding UI and transient geometry.

:root {
  --dynt-line-color: #ffbf00;
  --dynt-kinetic-color: #64c6ff;
}

[data-theme='light'] [data-dynt-surface] {
  --dynt-line-color: #8f5d00;
  --dynt-kinetic-color: #0076a8;
}

Controller tokens, selector groups, and target-local data attributes can override the global theme. Target-local configuration has final priority for supported channels.

Pause, update, reconcile, and destroy deliberately.

// Route or application boundary teardown.
kinetic.destroy();
formation.destroy();

destroy() is idempotent. Application-owned classes, attributes, inline properties, and priorities are restored exactly after the final controller releases each target.

Motion remains decoration; semantics stay application-owned.

• Decoration layers are hidden from assistive technology and never receive pointer events.
• Links, buttons, inputs, names, values, focus order, and keyboard behavior remain native.
• prefers-reduced-motion: reduce skips Formation travel and removes Kinetic tilt, drift, and waves while preserving meaningful state.
• Kinetic uses one controller scheduler, caps active surfaces, limits wave cells, and performs no continuous animation work while idle.
• Do not use motion or line color as the only indication of required information.

Read the complete accessibility contract and performance budgets.

Check the boundary before tuning the effect.