Flexible Types & Target Resolution

Many properties in AnimX accept multiple formats, including strings, elements, or arrays. This guide explains how target resolution and flexible types operate.

---

Target Resolution

When an API parameter expects a target (such as target, targets, source, repeller, or bounds), it supports several data types, including DOM nodes, CSS selectors, arrays, and plain JavaScript objects.

string (CSS Selectors)

AnimX automatically resolves CSS selector strings using document.querySelectorAll() to find matching elements.

import { animate } from 'animx';

animate('.my-box', { x: 100 });

Element (Raw DOM Node)

Raw HTML elements are accepted directly.

import { animate } from 'animx';

const box = document.getElementById('hero-box');
animate(box, { x: 100 });

NodeList

NodeLists returned by standard DOM querying methods are handled automatically.

import { animate } from 'animx';

const boxes = document.querySelectorAll('.box');
animate(boxes, { x: 100 });

Array<Element>

Arrays containing HTML elements are supported. This accommodates elements filtered or mapped in JavaScript.

import { animate } from 'animx';

const boxes = Array.from(document.querySelectorAll('.box'));
const visibleBoxes = boxes.filter(b => b.style.opacity !== '0');

animate(visibleBoxes, { x: 100 });

Object (Literal and State Objects)

AnimX supports plain JavaScript objects as animation targets. You can pass any object containing numeric properties directly to animate() or timelines to tween arbitrary state variables, such as scores, coordinates, or application data.

import { animate } from 'animx';

const state = { score: 0, health: 100 };

animate(state, {
  score: 1000,
  health: 50,
  duration: 2,
  onUpdate: function() {
    console.log(this.targets[0].score);
  }
});

Additionally, physics boundaries and interactable configurations accept coordinate literal objects instead of DOM elements. Only the required boundaries need to be defined (e.g., providing only { minY: 500 } sets a floor while leaving other axes unbounded).

Drag the orb!

60 FPS

import { Interactable } from 'animx/plugins/Interactable';

Interactable.create('.orb', {
  bounds: { minX: -120, maxX: 120 }
});

---

Function-Based Values

Target properties such as x, y, opacity, scale, and other animatable CSS values accept functions. The function executes once for each target element, enabling dynamic value generation.

Function Signature

(targetElement, index?, targetsArray?) => number | string

• targetElement: The specific HTML element being animated.
• index (optional): The 0-based index of the current element.
• targetsArray (optional): The full array of all targeted elements.

Dynamic Spacing

60 FPS

import { animate } from 'animx';

animate('.box', {
  x: (targetElement, index) => index * 40, 
});

State-based Values

60 FPS

import { animate } from 'animx';

animate('.card', {
  y: (targetElement) => parseFloat(targetElement.dataset.dropHeight)
});

---

Array Keyframes (Property Keyframes)

You can pass an array of values to any animatable property. AnimX will automatically distribute these values evenly across the duration of the animation, creating a multi-step sequence for that specific property.

60 FPS

import { animate } from 'animx';

animate('.dot', {
  x: [0, 80, 160, 240, 320],
  y: [0, -40, 0, -40, 0], // Bouncing path
  backgroundColor: ['#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6'],
  duration: 2,
  ease: 'linear'
});

This is equivalent to creating a timeline or writing explicit keyframes, but is much faster and cleaner for simple multi-step interpolations.

---

Special Keywords

Specific plugins accept keyword strings for certain properties.

'pointer'

In physics plugins, the 'pointer' keyword acts as the source or repeller. This maps the physics origin to pointer movement rather than an HTML element.

import { applyRepulsion } from 'animx/plugins/Dynamics';

applyRepulsion('.dots', {
  source: 'pointer',
  force: 1000
});