Skip to content

Slots API

Jump to bottom
Abdelrahman Ashraf edited this page Jan 14, 2026 · 1 revision

Slots API

Slots provide a runtime theming system for Lottie animations, allowing you to dynamically override animation properties like colors, text, gradients, and transform values without modifying the source animation file.

Specification: Slots are defined in the Lottie Animation Format Specification. Properties in the animation marked with a sid (slot identifier) field reference slot definitions, enabling centralized control—updating one slot value simultaneously affects all properties referencing it.

Table of Contents

Overview

Slots are named placeholders defined in Lottie animations that can be overridden at runtime. They enable:

  • Runtime theming: Change colors, text, and other properties without reloading
  • Personalization: Customize animations with user-specific content
  • A/B testing: Swap visual elements dynamically
  • Localization: Change text content for different languages

Basic Usage

import { DotLottie } from '@lottiefiles/dotlottie-web';

const dotLottie = new DotLottie({
  canvas: document.getElementById('canvas'),
  src: 'animation.lottie',
  autoplay: true,
});

dotLottie.addEventListener('load', () => {
  // Get available slots
  const slotIds = dotLottie.getSlotIds();
  console.log('Available slots:', slotIds);

  // Override a color slot
  dotLottie.setColorSlot('Background', [1, 0, 0]); // Red
});

Getting Slot Information

getSlotIds(): string[]

Returns an array of all slot IDs available in the loaded animation.

const slotIds = dotLottie.getSlotIds();
// ['Background', 'PrimaryColor', 'Title', 'IconScale']

getSlotType(slotId: string): SlotType | undefined

Returns the type of a specific slot. Possible types:

Type Description
'color' RGB/RGBA color values
'scalar' Single numeric value (rotation, opacity, etc.)
'vector' 2D point (position, scale, anchor point, etc.)
'text' Text document with content, size, color
'gradient' Gradient color stops
'image' Image asset reference 
const type = dotLottie.getSlotType('Background');
// 'color'

getSlot(slotId: string): unknown

Returns the current value of a slot. The return type depends on the slot type.

const value = dotLottie.getSlot('Background');
// Returns the slot's animated property structure

getSlots(): Record<string, unknown>

Returns all slots as an object with slot IDs as keys.

const allSlots = dotLottie.getSlots();
// { Background: {...}, PrimaryColor: {...}, ... }

Slot Types

Color Slots

Colors are represented as RGB or RGBA arrays with values normalized to the range [0, 1].

type Color = [number, number, number] | [number, number, number, number];
// [r, g, b] or [r, g, b, a]

Examples:

[1, 0, 0]       // Red (RGB)
[0, 1, 0]       // Green (RGB)
[0, 0, 1, 0.5]  // Blue at 50% opacity (RGBA)
[0.5, 0.5, 0.5] // 50% Gray

Converting from hex:

function hexToRgb(hex: string): [number, number, number] {
  const r = parseInt(hex.slice(1, 3), 16) / 255;
  const g = parseInt(hex.slice(3, 5), 16) / 255;
  const b = parseInt(hex.slice(5, 7), 16) / 255;
  return [r, g, b];
}

dotLottie.setColorSlot('Background', hexToRgb('#FF5733'));

Scalar Slots

Scalars are single numeric values used for properties like rotation, opacity, or any single-dimension value.

type ScalarSlotValue = number;

Examples:

45      // Rotation in degrees
50     // 50% opacity (if the slot controls opacity)
100     // Scale percentage

Vector Slots

Vectors are 2D points used for position, scale, anchor point, etc.

type Vector = [number, number];
// [x, y]

Examples:

[100, 100]     // 2D position or scale
[256, 256]     // Center position in a 512x512 canvas

Text Slots

Text slots contain a text document with multiple properties:

interface TextDocument {
  t?: string;   // Text content
  s?: number;   // Font size
  f?: string;   // Font family
  fc?: Color;   // Fill color [r, g, b] or [r, g, b, a]
  sc?: Color;   // Stroke color
  sw?: number;  // Stroke width
  j?: 0 | 1 | 2; // Justify: 0=left, 1=right, 2=center
  lh?: number;  // Line height
  tr?: number;  // Tracking (letter spacing)
}

Examples:

// Full text document
{ t: 'Hello World', s: 48, fc: [1, 1, 1] }

// Just change the text content
{ t: 'New Text' }

// Change size and color
{ s: 72, fc: [1, 0, 0] }

Gradient Slots

Gradients are flat arrays of color stops. Each stop consists of a position (0-1) followed by RGB values.

type Gradient = number[];
// Format: [pos1, r1, g1, b1, pos2, r2, g2, b2, ...]

Examples:

// Red to Blue gradient (2 stops)
[
  0, 1, 0, 0,   // Position 0: Red
  1, 0, 0, 1    // Position 1: Blue
]

// Red to Green to Blue gradient (3 stops)
[
  0,   1, 0, 0,   // Position 0: Red
  0.5, 0, 1, 0,   // Position 0.5: Green
  1,   0, 0, 1    // Position 1: Blue
]

// With opacity stops (appended after color stops)
// Color stops + opacity stops
[
  0, 1, 0, 0, 1, 0, 0, 1,  // Colors: red to blue
  0, 1,                      // Opacity at position 0: 100%
  1, 0.5                     // Opacity at position 1: 50%
]

Understanding Slot Values

When you read a slot value using getSlot(), you receive the Lottie animated property structure as defined in the Lottie specification. Each slot contains a p property holding the actual value:

Static Values

For non-animated properties, the value is in the k property:

{
  "a": 0,
  "k": [1, 0, 0]
}
  • a: Animation flag (0 = static, 1 = animated)
  • k: The value (color, scalar, vector, etc.)

Animated Values (Keyframes)

For animated properties, k contains an array of keyframes:

{
  "a": 1,
  "k": [
    { "t": 0, "s": [1, 0, 0] },
    { "t": 30, "s": [0, 1, 0] },
    { "t": 60, "s": [0, 0, 1] }
  ]
}

Keyframe structure:

interface Keyframe<T> {
  t: number;      // Time (frame number)
  s: T;           // Start value at this keyframe
  h?: 0 | 1;      // Hold (1 = no interpolation to next keyframe)
  i?: BezierHandle; // Incoming bezier handle (easing)
  o?: BezierHandle; // Outgoing bezier handle (easing)
}

Full Slot Structure

The complete slot object wraps the animated property in a p property:

{
  "p": {
    "a": 0,
    "k": [1, 0, 0]
  }
}

Setting Slot Values

setColorSlot(slotId: string, value: ColorSlotValue): boolean

Set a color slot with RGB/RGBA values.

// Static color (red)
dotLottie.setColorSlot('Background', [1, 0, 0]);

// With alpha
dotLottie.setColorSlot('Background', [1, 0, 0, 0.5]);

// Animated color (keyframes)
dotLottie.setColorSlot('Background', [
  { t: 0, s: [1, 0, 0] },   // Red at frame 0
  { t: 60, s: [0, 0, 1] }   // Blue at frame 60
]);

setScalarSlot(slotId: string, value: ScalarSlotValue): boolean

Set a scalar (single number) slot.

// Static value
dotLottie.setScalarSlot('Rotation', 45);
dotLottie.setScalarSlot('Opacity', 50);

// Animated value
dotLottie.setScalarSlot('Rotation', [
  { t: 0, s: 0 },
  { t: 60, s: 360 }
]);

setVectorSlot(slotId: string, value: VectorSlotValue): boolean

Set a vector slot (position, scale, anchor point, etc.).

// Static vector
dotLottie.setVectorSlot('Scale', [150, 150]);
dotLottie.setVectorSlot('Position', [100, 200]);

// Animated vector
dotLottie.setVectorSlot('Position', [
  { t: 0, s: [0, 0] },
  { t: 60, s: [100, 200] }
]);

setTextSlot(slotId: string, value: TextSlotValue): boolean

Set a text slot. Supports partial updates - only provided properties are changed.

// Set all properties
dotLottie.setTextSlot('Title', {
  t: 'Hello World',
  s: 48,
  fc: [1, 1, 1]
});

// Partial update - only change text content
dotLottie.setTextSlot('Title', { t: 'New Text' });

// Change font size and color
dotLottie.setTextSlot('Title', {
  s: 72,
  fc: [1, 0, 0]
});

setGradientSlot(slotId: string, value: GradientSlotValue): boolean

Set a gradient slot with color stops.

// Red to blue gradient
dotLottie.setGradientSlot('Gradient', [
  0, 1, 0, 0,   // Position 0: Red
  1, 0, 0, 1    // Position 1: Blue
]);

// Three-color gradient
dotLottie.setGradientSlot('Gradient', [
  0,   1, 0, 0,   // Red
  0.5, 1, 1, 0,   // Yellow
  1,   0, 1, 0    // Green
]);

// Animated gradient
dotLottie.setGradientSlot('Gradient', [
  { t: 0, s: [0, 1, 0, 0, 1, 0, 0, 1] },
  { t: 60, s: [0, 0, 1, 0, 1, 1, 0, 0] }
]);

setSlots(slots: Record<string, unknown>): void

Set multiple slots at once using the raw Lottie slot format.

dotLottie.setSlots({
  Background: { a: 0, k: [1, 0, 0] },
  Scale: { a: 0, k: [150, 150] }
});

Resetting and Clearing Slots

resetSlot(slotId: string): boolean

Reset a single slot to its original value from the animation file.

dotLottie.resetSlot('Background');

resetSlots(): boolean

Reset all slots to their original values.

dotLottie.resetSlots();

clearSlot(slotId: string): boolean

Clear a single slot's custom value.

dotLottie.clearSlot('Background');

clearSlots(): boolean

Clear all slot custom values.

dotLottie.clearSlots();

Complete Examples

Theme Switcher

const themes = {
  light: {
    background: [1, 1, 1],
    primary: [0.2, 0.4, 0.8],
    text: [0.1, 0.1, 0.1]
  },
  dark: {
    background: [0.1, 0.1, 0.1],
    primary: [0.4, 0.6, 1],
    text: [0.9, 0.9, 0.9]
  }
};

function applyTheme(theme: 'light' | 'dark') {
  const colors = themes[theme];
  dotLottie.setColorSlot('Background', colors.background);
  dotLottie.setColorSlot('PrimaryColor', colors.primary);
  dotLottie.setColorSlot('TextColor', colors.text);
}

// Apply dark theme
applyTheme('dark');

Dynamic Text Content

function updateGreeting(name: string, fontSize: number = 36) {
  dotLottie.setTextSlot('Greeting', {
    t: `Hello, ${name}!`,
    s: fontSize,
    fc: [0, 0.5, 1]
  });
}

updateGreeting('Alice', 48);

Interactive Color Picker

const colorPicker = document.getElementById('color-picker');

colorPicker.addEventListener('input', (e) => {
  const hex = e.target.value;
  const rgb = hexToRgb(hex);
  dotLottie.setColorSlot('UserColor', rgb);
});

function hexToRgb(hex: string): [number, number, number] {
  const r = parseInt(hex.slice(1, 3), 16) / 255;
  const g = parseInt(hex.slice(3, 5), 16) / 255;
  const b = parseInt(hex.slice(5, 7), 16) / 255;
  return [r, g, b];
}

Slot Type Inspection

dotLottie.addEventListener('load', () => {
  const slotIds = dotLottie.getSlotIds();

  console.log('Animation Slots:');
  slotIds.forEach(id => {
    const type = dotLottie.getSlotType(id);
    const value = dotLottie.getSlot(id);
    console.log(`  ${id}: ${type}`, value);
  });
});

Conditional Slot Updates

function updateSlotByType(slotId: string, value: unknown) {
  const type = dotLottie.getSlotType(slotId);

  switch (type) {
    case 'color':
      dotLottie.setColorSlot(slotId, value as Color);
      break;
    case 'scalar':
      dotLottie.setScalarSlot(slotId, value as number);
      break;
    case 'vector':
      dotLottie.setVectorSlot(slotId, value as Vector);
      break;
    case 'text':
      dotLottie.setTextSlot(slotId, value as TextDocument);
      break;
    case 'gradient':
      dotLottie.setGradientSlot(slotId, value as Gradient);
      break;
    default:
      console.warn(`Unknown slot type: ${type}`);
  }
}

API Reference Summary

Method Description
getSlotIds() Get all slot IDs in the animation
getSlotType(slotId) Get the type of a slot
getSlot(slotId) Get the current value of a slot
getSlots() Get all slots as an object
setColorSlot(slotId, value) Set a color slot
setScalarSlot(slotId, value) Set a scalar slot
setVectorSlot(slotId, value) Set a vector slot
setTextSlot(slotId, value) Set a text slot
setGradientSlot(slotId, value) Set a gradient slot
setSlots(slots) Set multiple slots at once
resetSlot(slotId) Reset a slot to its original value
resetSlots() Reset all slots
clearSlot(slotId) Clear a slot's custom value
clearSlots() Clear all slot custom values

Clone this wiki locally