hyperframes/skills/hyperframes-animation/rules/counting-dynamic-scale.md

name, description, metadata

name	description	metadata
counting-dynamic-scale	Counter animation where the value counts up while transform scale grows to its final size, creating escalating visual weight without per-frame text reflow.	tags counter, counting, scale, transform, number, dynamic, emphasis

Counting with Dynamic Scale

A number counts from A → B while its transform scale grows to the final size. The effect preserves escalating visual weight without tweening font-size or forcing text layout on every frame.

How It Works

A single paused timeline drives two synchronized tweens:

1. The numeric value (rendered as DOM text via onUpdate)
2. The counter transform (scale: START_SCALE → scale: 1)

As the number gets bigger, the text grows in place — visually communicating “this is impressive” while keeping the final font size static in CSS.

Easing

Pick by drama desired (the choice is discrete; coefficient is implicit):

GSAP ease	Effect
power1.out	Mild — slight deceleration
power2.out	Default — ease-out, fast start slow end
power3.out	Strong — dramatic deceleration ⭐ recommended
expo.out	Very dramatic — almost stops at the end

power3.out matches the polynomial 1 - (1-x)^k family at k ≈ 2.5 — number rushes up then slows dramatically at the peak.

HTML

<div
  class="scene"
  data-composition-id="counter-scene"
  data-start="0"
  data-duration="3"
  data-track-index="0"
>
  <div class="counter-wrap">
    <span class="counter" id="counter">0</span><span class="counter-suffix">{suffix}</span>
  </div>
  <div class="counter-label">{label}</div>
</div>

CSS

.scene {
  position: relative;
  width: 100%;
  height: 100%;
  display: grid;
  place-items: center;
  background: {bgColor};
}

.counter-wrap {
  display: flex;
  align-items: baseline;
  justify-content: center;
  gap: 8px;
  /* Fixed-width container prevents layout shift as digit count changes */
  width: {counterContainerWidth};
  text-align: center;
}

.counter {
  font-family: {font};
  font-weight: 900;
  color: {textColor};
  /* MANDATORY — tabular-nums keeps digits the same width */
  font-variant-numeric: tabular-nums;
  /* Final size is static. GSAP animates transform scale, not font-size. */
  display: inline-block;
  font-size: {endSize};
  transform-origin: center center;
  letter-spacing: -2px;
  line-height: 1;
}

.counter-suffix {
  font-family: {font};
  font-weight: 800;
  color: {accentColor};
  font-size: {suffixSize};
  opacity: 0;
  transform: translateY(20px);
}

.counter-label {
  margin-top: 24px;
  font-family: {font};
  font-size: {labelSize};
  color: {mutedTextColor};
  text-align: center;
}

GSAP Timeline

<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  const counter = document.getElementById("counter");
  const state = { value: 0 };
  const START_SCALE = START_SIZE / END_SIZE;

  // Count value. onUpdate changes text only.
  tl.to(
    state,
    {
      value: TARGET_VALUE,
      duration: COUNT_DUR,
      ease: COUNT_EASE,
      onUpdate: () => {
        counter.textContent = Math.round(state.value).toLocaleString();
      },
    },
    0,
  );

  // Visual growth uses a compositor transform and shares the count timing.
  tl.fromTo(
    counter,
    { scale: START_SCALE },
    { scale: 1, duration: COUNT_DUR, ease: COUNT_EASE },
    0,
  );

  // Suffix slides in after count completes
  tl.to(
    ".counter-suffix",
    {
      opacity: 1,
      y: 0,
      duration: SUFFIX_DUR,
      ease: `back.out(${SUFFIX_BOUNCE_FACTOR})`,
    },
    COUNT_DUR,
  );

  // Label fades in early
  tl.from(
    ".counter-label",
    {
      opacity: 0,
      y: 12,
      duration: LABEL_DUR,
      ease: "power2.out",
    },
    LABEL_AT,
  );

  window.__timelines["counter-scene"] = tl;
</script>

How to Choose Values

• TARGET_VALUE — the number the counter lands on

  • Effects: 2–3 digits reads best at hero size; 4+ digits requires wider container
  • Constraints: must fit horizontally at END_SIZE inside the container

• START_SIZE / END_SIZE — design inputs used once to calculate START_SCALE

  • Range: START_SIZE ≈ 40–60 % of END_SIZE
  • Effects: smaller START_SIZE = more dramatic growth; larger = subtler
  • Constraints: set CSS font-size to END_SIZE; never tween either value. END_SIZE × digit count must fit the container width without clipping

• COUNT_DUR — count + scale tween duration

  • Range: 1.2–2.5 s
  • Effects: shorter = aggressive; longer = settled, gives reading time
  • Constraints: must allow the eye to read the digits scrolling past; below ~0.8 s reads as a flash

• COUNT_EASE — shared ease for the value and transform scale

  • Discrete choice: power2.out, power3.out, expo.out (see table above)
  • Constraint: avoid back.out / elastic.out — overshoot reads as unstable data

• SUFFIX_DUR — duration of the suffix slide-in

  • Range: 0.3–0.6 s
  • Effects: shorter = snap; longer = floats
  • Constraints: must fire after the count lands (started at COUNT_DUR), not during

• SUFFIX_BOUNCE_FACTOR — back.out coefficient on the suffix entry

  • Range: 1.4–2.0
  • Effects: 1.4 = small overshoot; 2.0 = bouncy

• LABEL_AT / LABEL_DUR — when and how long the label fades in

  • Range: LABEL_AT < COUNT_DUR / 2 (label arrives before count peaks); LABEL_DUR 0.4–0.7 s

Variations

Direct innerText tween (no proxy object)

The GSAP inspector reads innerText directly, so a number-only counter can skip the state proxy:

tl.to(
  counter,
  { innerText: TARGET_VALUE, duration: COUNT_DUR, ease: COUNT_EASE, snap: { innerText: 1 } },
  0,
);

snap: { innerText: 1 } keeps it integer. Keep the proxy-object onUpdate form above when you need locale formatting (toLocaleString) or suffix logic. In either form, the synchronized scale remains a separate transform tween at timeline position 0.

3D depth entry

Combine with translateZ for parallax-style depth on entry:

tl.from(
  ".counter",
  {
    z: -300,
    duration: 0.6,
    ease: "power2.out",
    // requires parent or .counter itself to have perspective set
  },
  0,
);

CSS prerequisite:

.counter-wrap {
  perspective: 1000px;
}
.counter {
  transform-style: preserve-3d;
}

Multi-stat coordinated reveal

For 3 stats counting in parallel, share the SAME ease and duration so they finish together — visually a chord, not arpeggio. Each stat usually also needs a paired graphic (bar / ring / stars) — don't stop at the number; see stat-bars-and-fills.md:

["#stat1", "#stat2", "#stat3"].forEach((sel, i) => {
  const obj = { v: 0 };
  tl.to(
    obj,
    {
      v: TARGETS[i],
      duration: COUNT_DUR,
      ease: COUNT_EASE,
      onUpdate: () => (document.querySelector(sel).textContent = Math.round(obj.v)),
    },
    0,
  ); // same start position — chord
});

Key Principles

• Synchronized value + scale at one timeline position so the two tweens share an ease and stay coordinated
• font-variant-numeric: tabular-nums is mandatory — without it digit-count transitions (e.g. 9 → 10 → 100) cause visible jitter as glyph widths change
• Fixed-width container as belt-and-suspenders — even with tabular-nums, glyph shape changes can shift baselines
• Grow in place, don't bounce — the number should feel weighty, not springy. power3.out ends at exact value; back.out overshoots and feels cartoonish
• Start small enough to grow noticeably (~50 % of final size); end large enough to feel decisive but not clip viewport
• Never set fontSize in onUpdate — final type size is static CSS; only the transform changes per frame
• Suffix animates AFTER the count, not during — gives the number its own beat
• ❗ Label is BIG TEXT, not a page-style tiny caption — for VIDEO, a small paragraph-style caption below a hero-size number reads as visual noise. Use display-size, uppercase, tracked label so the layout is "two-line big-text"; the label is part of the headline, not a footer.

Critical Constraints

• tabular-nums mandatory — required CSS for layout stability
• Timeline must be paused: gsap.timeline({ paused: true }). Never tl.play()
• Registry key = data-composition-id: window.__timelines["counter-scene"] must match scene root
• onUpdate mutates DOM: HF runtime seeks the timeline frame-by-frame, so onUpdate runs on every seek call. Keep onUpdate work O(1) — set text only, with no style writes or DOM creation
• Math.round not Math.floor — half-way through the final integer should display the final value briefly, not the previous one
• Avoid back.out / elastic.out for the counter itself — overshoot makes the number look unstable (it's data, not decoration)

Combinations

• stat-bars-and-fills.md — the paired graphic beside the number (growth bars / progress ring / star wipe). A stat scene is usually BOTH rules: the count-up here + a fill there. Give the fill the same ease and duration so number and graphic land as one beat.
• svg-path-draw.md — icons drawing in around the number
• center-outward-expansion.md — related icons exploding outward synced to count peak

Pairs with HF skills

• /hyperframes-animation — timeline + onUpdate API
• /hyperframes-core — composition wiring, data-* attributes
• /hyperframes-cli — hyperframes lint to verify scene