Params

Params make one spec cover several variants. A param is a named number with a default value. Users override it by name, for example to show 5 dots instead of 3.

Declare and use a param

1. Declare the param and its default in params.
2. Write { "$param": "name" } where a number is allowed.

{
  "$schema": "https://maitrungduc1410.github.io/loader-kit/schema/v1.json",
  "schemaVersion": 1,
  "name": "TypingDots",
  "duration": 1.2,
  "params": { "count": 3, "rise": -0.15, "dim": 0.4 },
  "layout": { "type": "row", "count": { "$param": "count" }, "gap": 0.1 },
  "shape": { "type": "circle" },
  "stagger": { "each": 0.15 },
  "tracks": [
    {
      "property": "translateY",
      "keyTimes": [0, 0.3, 0.6, 1],
      "values": [0, { "$param": "rise" }, 0, 0],
      "easing": ["easeOut", "easeIn", "linear"]
    },
    {
      "property": "opacity",
      "keyTimes": [0, 0.3, 0.6, 1],
      "values": [{ "$param": "dim" }, 1, { "$param": "dim" }, { "$param": "dim" }]
    }
  ]
}

TypingDotsOpen in playground →

Freeze a frame

cycleProgress

null

This typing indicator has three params:

Param	Default	Used in
count	3	layout.count
rise	-0.15	the highest point of translateY (negative is up)
dim	0.4	the opacity between bounces

Where $param is allowed

Any number in a layout, a shape, track values or rest can be a $param. That includes counts, sizes, gaps, angles, stroke widths and corner radii.

These fields must be plain numbers: duration, part duration, durations, stagger, keyTimes, easing control points and perspective.

Overriding params

Users pass overrides by name on every platform:

HTML

<loader-kit params='{"count": 4, "rise": -0.25}'></loader-kit>

TypeScript

view.params = { count: 4, rise: -0.25 };

Kotlin

loader.params = mapOf("count" to 4.0, "rise" to -0.25)

Swift

loader.params = ["count": 4, "rise": -0.25]

C#

indicator.Params = new Dictionary<string, double> { ["count"] = 4, ["rise"] = -0.25 };

Rules

• Overrides for names the spec does not declare are ignored.
• A $param that names an undeclared param is a validation error: layout.count uses unknown param "cout".
• Param defaults must be finite numbers.
• Counts are rounded to the nearest integer (0.5 rounds up) and are at least 1.
• Values that come from params are not range-checked by validate(). A sweep is clamped to [0, 2π], and a ring with no room for its stroke draws nothing.
• Changing params restarts the animation.

Params and element counts

A stagger array or durations must have one entry per element. validate() never compares list lengths with the element count, and when count comes from a param the count is only known once the user's params are applied. So a list that is too short is reported when the spec is prepared, not by validate(). Prefer stagger: { "each": ... } with a param count.

Naming tips

• Use names that describe the effect, not the field: minScale and minOpacity rather than value1.
• Pick defaults that look good on their own. Most users never override params.
• Keep the count of params small. A param that nobody changes is noise.