svg-text-animate

To render the animation, you must first load the font and then call the create method.

Workflow

1. setFont(): An asynchronous method that loads the font file provided in the constructor. It returns a Promise and should be called once.
2. create(text, selector): Generates the SVG animation from the provided text string and inserts it into the DOM element matching the selector. This method clears the selector's content before inserting.

Note: add(text, selector) (available since v1.2.0) performs the same action but inserts the animation without clearing the selector first.

Example

await opensans.setFont();
opensans.create("Hello World", "#target-element");

import SVGTextAnimate from 'svg-text-animate';

const opensans = new SVGTextAnimate("https://path/to/font.woff", {
  "duration": 500,
  "mode": "sync"
}, {
  "stroke": "white",
  "font-size": 23
});

// 1. Load font
await opensans.setFont();

// 2. Create animation
opensans.create("Try it", ".button");

To create an instance of SVGTextAnimate, use the following signature:

SVGTextAnimate(fontfile, options, stroke, creator)

Parameters

• fontfile (String, Required): Path to a font file (WOFF, OTF, or TTF).
• options (Object, Required): Configuration for the animation timing and behavior.
• stroke (Object, Required): Configuration for the visual appearance (stroke, size, etc.).
• creator (String, Optional): The animation mode. Defaults to css. Use svg for SMIL SVG animations if CSS is not supported.

Note: In version 1.2.0, font-size was moved from options to the stroke object.

import SVGTextAnimate from 'svg-text-animate';

const opensans = new SVGTextAnimate("https://path/to/font.woff", {
  "duration": 300,
  "direction": "normal",
  "fill-mode": "forwards",
  "delay": 150,
  "mode": "delay"
}, {
  "stroke": "#005792",
  "stroke-width": "2px",
  "font-size": 55,
  "fill-color":"white"
});

You can dynamically update the animation or visual settings using chainable methods. Both methods return the current instance to allow chaining.

• setOptions(options): Updates the animation timing/behavior settings. Accepts an object with the same keys as the initial options parameter.
• setStroke(stroke): Updates the visual stroke and font settings. Accepts an object with the same keys as the initial stroke parameter.

Example

opensans
  .setOptions({
    "duration": 500,
    "mode": "sync"
  })
  .setStroke({
    "stroke": "white",
    "font-size": 23
  })
  .create("Updated Text", ".container");

opensans.setOptions({
  "duration": 500,
  "timing-function": "linear",
  "direction": "normal",
  "fill-mode": "forwards",
  "delay": 50,
  "mode": "sync"
}).setStroke({
  "stroke": "white",
  "stroke-width": "2px",
  "font-size": 23,
  "fill-color":"white"
}).create("Try it", ".button");

When initializing an animation, you can provide an options object to control the timing and behavior of the SVG text animation. If no options are provided, the following defaults are used:

• duration: Animation duration in milliseconds (default: 1000)
• timing-function: CSS timing function (default: 'linear')
• iteration-count: Number of times the animation repeats (default: 1)
• direction: Animation direction ('normal', 'reverse', 'alternate', or 'alternate-reverse') (default: 'normal')
• fill-mode: CSS fill mode ('none', 'forwards', 'backwards', or 'both') (default: 'forwards')
• delay: Delay before the animation starts in milliseconds (default: 0)
• mode: Animation synchronization mode ('sync' or 'async') (default: 'sync')

Note that keys like timing-function, iteration-count, and fill-mode use kebab-case to match CSS property names.

const options = {
  duration: 2000,
  'timing-function': 'ease-in-out',
  'iteration-count': Infinity,
  direction: 'alternate',
  'fill-mode': 'forwards',
  delay: 500,
  mode: 'async'
};

The AnimationOptions interface defines how the text animation behaves over time. You can control the speed, repetition, and the relationship between individual character animations using the mode property.

Key properties include:

• duration: Total animation time in milliseconds.
• mode: Determines the animation pattern. Use "sync" for simultaneous animation, "delay" for staggered animation, or "onebyone" for sequential animation.
• delay: The delay between individual character animations in milliseconds.
• "timing-function": CSS timing function (e.g., ease-in) or SVG calcMode.
• "iteration-count": Number of times to repeat, or strings like "infinite" or "indefinite".
• direction: Animation direction.
• "fill-mode": CSS fill mode behavior.

const options: AnimationOptions = {
  duration: 1000,
  mode: 'onebyone',
  delay: 50,
  'timing-function': 'ease-out',
  'iteration-count': 'infinite'
};