react-lottie 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.2.0](https://github.com/chenqingspring/react-lottie/compare/v2.1.0...v2.2.0) (2026-11-05)
+
+### Features
+
+* add a `colorFilters` prop that replaces the colors of fills, strokes and solid layers by keypath, mirroring lottie-react-native's API. The filters are applied to a copy of `animationData`; changing them reloads the animation while preserving the current frame and playback state ([#144](https://github.com/chenqingspring/react-lottie/issues/144))
+
 ## [2.1.0](https://github.com/chenqingspring/react-lottie/compare/v2.0.1...v2.1.0) (2026-11-05)
 
 ### Features

package/README.md

@@ -187,6 +187,34 @@ A segment also has to be reachable with `loop`/`autoplay` as usual: with
 `loop: false` and `autoplay: false` the range only plays once you flip
 `isStopped` or pass a new `segments` value.
 
+### Recolor an animation
+
+`colorFilters` replaces the colors of fills, strokes and solid layers named by
+a keypath, so one animation file can follow a theme (issue #144):
+
+```jsx
+<Lottie
+  options={defaultOptions}
+  colorFilters={[
+    { keypath: 'Pin 1.Shape 2.Fill 1', color: '#4f46e5' },
+    { keypath: 'Background', color: 'rgb(15, 23, 42)' },
+  ]}
+/>
+```
+
+A keypath is the dot-separated name chain from the layer down to the fill,
+stroke or solid, e.g. `layer.group.fill`. For a layer inside a precomposition,
+the composition name can be included (`Precomp.InnerLayer.Shape.Fill 1`) or
+omitted. `*` matches one level and `**` matches any number of levels; dots in
+a name can be escaped with a backslash. Colors accept hex, `rgb()`/`rgba()`,
+`hsl()`/`hsla()` and the basic CSS color names. Invalid filters are ignored.
+
+The filters are applied to `options.animationData`. Changing them reloads the
+animation, because lottie-web cannot recolor a loaded animation; the current
+frame and paused/playing state are preserved. Animations loaded from
+`options.path` are not recolored, since the JSON is fetched by lottie-web:
+load the JSON yourself and pass it as `animationData` instead.
+
 ### Imperative control
 
 A `ref` to the component exposes `play()`, `pause()`, `stop()`,
@@ -222,6 +250,11 @@ the object representing the animation settings that will be instantiated by body
 >
 >**rendererSettings** *required* 
 
+**colorFilters** *optional* [default: `[]`]
+
+Array of `{ keypath, color }` objects that replace the colors of fills,
+strokes and solid layers. See [Recolor an animation](#recolor-an-animation).
+
 **width** *optional* [default: `100%`]
 
 pixel value for containers width.

package/dist/colorFilters.js

@@ -0,0 +1,260 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parseColor = exports.colorFiltersAreEqual = exports.applyColorFilters = void 0;
+function _toConsumableArray(r) { return _arrayWithoutHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray(r) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _iterableToArray(r) { if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r); }
+function _arrayWithoutHoles(r) { if (Array.isArray(r)) return _arrayLikeToArray(r); }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+/* `colorFilters` mirrors lottie-react-native: every filter names a keypath in
+   the animation (layer → group → shape item) and the color to replace there.
+   lottie-web has no public API for recoloring a loaded animation, so the
+   animation JSON is cloned with the matching colors replaced and the animation
+   is loaded again. The caller's animationData is never mutated, because it may
+   be a frozen ESM import (#144). */
+
+var NAMED_COLORS = {
+  aqua: [0, 255, 255],
+  black: [0, 0, 0],
+  blue: [0, 0, 255],
+  cyan: [0, 255, 255],
+  fuchsia: [255, 0, 255],
+  gray: [128, 128, 128],
+  green: [0, 128, 0],
+  grey: [128, 128, 128],
+  lime: [0, 255, 0],
+  magenta: [255, 0, 255],
+  maroon: [128, 0, 0],
+  navy: [0, 0, 128],
+  olive: [128, 128, 0],
+  purple: [128, 0, 128],
+  red: [255, 0, 0],
+  silver: [192, 192, 192],
+  teal: [0, 128, 128],
+  white: [255, 255, 255],
+  yellow: [255, 255, 0]
+};
+var clampChannel = function clampChannel(value) {
+  return Math.min(255, Math.max(0, value));
+};
+var toFractions = function toFractions(channels) {
+  return channels.map(function (channel) {
+    return clampChannel(channel) / 255;
+  });
+};
+var parseHex = function parseHex(value) {
+  var match = /^#?([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value);
+  if (!match) return null;
+  var digits = match[1].length <= 4 ? match[1].split('').map(function (digit) {
+    return digit + digit;
+  }) : match[1].match(/.{2}/g);
+
+  /* The fourth value is alpha; lottie keeps the animation's own alpha, so it
+     is ignored here. */
+  return toFractions(digits.slice(0, 3).map(function (digit) {
+    return parseInt(digit, 16);
+  }));
+};
+var parseChannel = function parseChannel(token) {
+  var value = parseFloat(token);
+  if (Number.isNaN(value)) return null;
+  return token.endsWith('%') ? value * 255 / 100 : value;
+};
+var parseRgb = function parseRgb(value) {
+  var match = /^rgba?\(\s*([^)]+)\)$/i.exec(value);
+  if (!match) return null;
+  var channels = match[1].split(/[\s,/]+/).filter(Boolean).slice(0, 3).map(parseChannel);
+  if (channels.length !== 3 || channels.some(function (channel) {
+    return channel === null;
+  })) return null;
+  return toFractions(channels);
+};
+var hueToRgb = function hueToRgb(p, q, t) {
+  var hue = t;
+  if (hue < 0) hue += 1;
+  if (hue > 1) hue -= 1;
+  if (hue < 1 / 6) return p + (q - p) * 6 * hue;
+  if (hue < 1 / 2) return q;
+  if (hue < 2 / 3) return p + (q - p) * (2 / 3 - hue) * 6;
+  return p;
+};
+var parseHsl = function parseHsl(value) {
+  var match = /^hsla?\(\s*([^)]+)\)$/i.exec(value);
+  if (!match) return null;
+  var parts = match[1].split(/[\s,/]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  var hue = (parseFloat(parts[0]) % 360 + 360) % 360 / 360;
+  var saturation = parseFloat(parts[1]) / 100;
+  var lightness = parseFloat(parts[2]) / 100;
+  if (Number.isNaN(hue) || Number.isNaN(saturation) || Number.isNaN(lightness)) {
+    return null;
+  }
+  if (saturation === 0) return [lightness, lightness, lightness];
+  var q = lightness < 0.5 ? lightness * (1 + saturation) : lightness + saturation - lightness * saturation;
+  var p = 2 * lightness - q;
+  return [hueToRgb(p, q, hue + 1 / 3), hueToRgb(p, q, hue), hueToRgb(p, q, hue - 1 / 3)];
+};
+
+/* Accepts the CSS color forms an app is likely to use for theming. Anything
+   else (including CSS variables) is ignored rather than crashing the render. */
+var parseColor = exports.parseColor = function parseColor(value) {
+  if (typeof value !== 'string') return null;
+  var color = value.trim().toLowerCase();
+  if (NAMED_COLORS[color]) return toFractions(NAMED_COLORS[color]);
+  return parseHex(color) || parseRgb(color) || parseHsl(color);
+};
+var setColorArray = function setColorArray(target, color) {
+  if (!Array.isArray(target) || target.length < 3) return false;
+  target[0] = color[0];
+  target[1] = color[1];
+  target[2] = color[2];
+  return true;
+};
+
+/* A color property is either static (`k: [r, g, b, a]`) or animated
+   (`k: [{ s: [...], e: [...] }, ...]`). Replace both so an animated fill stays
+   recolored throughout its keyframes. */
+var setColorProperty = function setColorProperty(property, color) {
+  if (!property || !Array.isArray(property.k) || property.k.length === 0) return false;
+  if (typeof property.k[0] === 'number') {
+    return setColorArray(property.k, color);
+  }
+  var applied = false;
+  property.k.forEach(function (keyframe) {
+    if (!keyframe || _typeof(keyframe) !== 'object') return;
+    if (setColorArray(keyframe.s, color)) applied = true;
+    if (setColorArray(keyframe.e, color)) applied = true;
+  });
+  return applied;
+};
+var toHex = function toHex(color) {
+  return "#".concat(color.map(function (channel) {
+    return Math.round(channel * 255).toString(16).padStart(2, '0');
+  }).join(''));
+};
+
+/* Solid layers store their color as a hex string instead of a color array. */
+var setSolidColor = function setSolidColor(layer, color) {
+  if (typeof layer.sc === 'string') {
+    layer.sc = toHex(color);
+    return true;
+  }
+  return setColorArray(layer.sc, color);
+};
+
+/* Split on unescaped dots so layer names that contain a dot (`icon.dark`) can
+   be targeted with `icon\.dark`. */
+var splitKeypath = function splitKeypath(keypath) {
+  var parts = [];
+  var current = '';
+  for (var index = 0; index < keypath.length; index += 1) {
+    var character = keypath[index];
+    if (character === '\\' && index + 1 < keypath.length) {
+      current += keypath[index + 1];
+      index += 1;
+    } else if (character === '.') {
+      parts.push(current);
+      current = '';
+    } else {
+      current += character;
+    }
+  }
+  parts.push(current);
+  return parts;
+};
+
+/* `*` matches one level and `**` matches any number of levels, matching the
+   keypath conventions used by lottie-ios. */
+var _matchesKeypath = function matchesKeypath(pattern, path) {
+  if (pattern.length === 0) return path.length === 0;
+  if (pattern[0] === '**') {
+    for (var index = 0; index <= path.length; index += 1) {
+      if (_matchesKeypath(pattern.slice(1), path.slice(index))) return true;
+    }
+    return false;
+  }
+  if (path.length === 0) return false;
+  if (pattern[0] !== '*' && pattern[0] !== path[0]) return false;
+  return _matchesKeypath(pattern.slice(1), path.slice(1));
+};
+var colorFiltersAreEqual = exports.colorFiltersAreEqual = function colorFiltersAreEqual(first, second) {
+  if (first === second) return true;
+  if (!Array.isArray(first) || !Array.isArray(second) || first.length !== second.length) {
+    return false;
+  }
+  return first.every(function (filter, index) {
+    var other = second[index];
+    return Boolean(filter && other) && filter.keypath === other.keypath && filter.color === other.color;
+  });
+};
+var applyColorFilters = exports.applyColorFilters = function applyColorFilters(animationData, colorFilters) {
+  if (!animationData || !Array.isArray(colorFilters) || colorFilters.length === 0) {
+    return animationData;
+  }
+  var filters = colorFilters.filter(function (filter) {
+    return filter && typeof filter.keypath === 'string';
+  }).map(function (filter) {
+    return {
+      parts: splitKeypath(filter.keypath.trim()),
+      color: parseColor(filter.color)
+    };
+  }).filter(function (filter) {
+    return filter.color;
+  });
+  if (filters.length === 0) return animationData;
+  var data = JSON.parse(JSON.stringify(animationData));
+  var assets = new Map();
+  if (Array.isArray(data.assets)) {
+    data.assets.forEach(function (asset) {
+      if (asset && asset.id) assets.set(asset.id, asset);
+    });
+  }
+  var applied = false;
+  var recolor = function recolor(node, path) {
+    filters.forEach(function (filter) {
+      if (!_matchesKeypath(filter.parts, path)) return;
+      if (node.c && setColorProperty(node.c, filter.color)) applied = true;
+      if (node.ty === 1 && setSolidColor(node, filter.color)) applied = true;
+    });
+  };
+  var _walkShapes = function walkShapes(shapes, path) {
+    if (!Array.isArray(shapes)) return;
+    shapes.forEach(function (shape) {
+      if (!shape || _typeof(shape) !== 'object') return;
+      var shapePath = shape.nm ? [].concat(_toConsumableArray(path), [shape.nm]) : path;
+      recolor(shape, shapePath);
+      _walkShapes(shape.it, shapePath);
+      _walkShapes(shape.shapes, shapePath);
+    });
+  };
+
+  /* Precompositions are walked twice: once from the asset (so a keypath can
+     start at the inner layer name) and once from each layer that references
+     them (so `Precomp.InnerLayer...` also works). `refStack` prevents a
+     self-referencing composition from recursing forever. */
+  var _walkLayers = function walkLayers(layers, prefix, refStack) {
+    if (!Array.isArray(layers)) return;
+    layers.forEach(function (layer) {
+      if (!layer || _typeof(layer) !== 'object') return;
+      var path = layer.nm ? [].concat(_toConsumableArray(prefix), [layer.nm]) : prefix;
+      recolor(layer, path);
+      _walkShapes(layer.shapes, path);
+      var asset = layer.refId ? assets.get(layer.refId) : null;
+      if (layer.ty === 0 && asset && !refStack.includes(layer.refId)) {
+        _walkLayers(asset.layers, path, [].concat(_toConsumableArray(refStack), [layer.refId]));
+      }
+    });
+  };
+  _walkLayers(data.layers, [], []);
+  if (Array.isArray(data.assets)) {
+    data.assets.forEach(function (asset) {
+      return _walkLayers(asset.layers, [], []);
+    });
+  }
+  return applied ? data : animationData;
+};

package/dist/index.js

@@ -7,6 +7,7 @@ exports["default"] = void 0;
 var _react = _interopRequireDefault(require("react"));
 var _propTypes = _interopRequireDefault(require("prop-types"));
 var _lottieWeb = _interopRequireDefault(require("lottie-web"));
+var _colorFilters = require("./colorFilters");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
@@ -56,7 +57,8 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     value: function componentDidMount() {
       var _this$props = this.props,
         options = _this$props.options,
-        eventListeners = _this$props.eventListeners;
+        eventListeners = _this$props.eventListeners,
+        colorFilters = _this$props.colorFilters;
       var loop = options.loop,
         autoplay = options.autoplay,
         animationData = options.animationData,
@@ -64,16 +66,28 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         renderer = _options$renderer === void 0 ? 'svg' : _options$renderer,
         rendererSettings = options.rendererSettings,
         segments = options.segments;
+
+      /* Keep the caller's data and filter list around so a later update can tell
+         whether either actually changed. */
+      this.animationData = animationData;
+      this.colorFilters = colorFilters;
+      var filteredAnimationData = (0, _colorFilters.applyColorFilters)(animationData, colorFilters);
       this.options = {
         container: this.el,
         renderer: renderer,
         loop: loop !== false,
         autoplay: autoplay !== false,
         segments: segments !== false,
-        animationData: animationData,
+        animationData: filteredAnimationData,
         rendererSettings: rendererSettings
       };
       this.options = _objectSpread(_objectSpread({}, this.options), options);
+      /* Spreading `options` restored the unfiltered data; use the filtered copy
+         after the merge. */
+      this.options.animationData = filteredAnimationData;
+      if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && Array.isArray(colorFilters) && colorFilters.length > 0 && !animationData) {
+        console.warn('[react-lottie] colorFilters requires options.animationData; ' + 'animations loaded from options.path are not recolored.');
+      }
       this.anim = _lottieWeb["default"].loadAnimation(this.options);
       this.registerEvents(eventListeners);
       this.setSpeed();
@@ -101,17 +115,35 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
   }, {
     key: "componentDidUpdate",
     value: function componentDidUpdate(prevProps) {
-      /* Recreate the animation handle if the data or its remote path changed.
-         Done here rather than in componentWillUpdate, which React has deprecated
-         and which is unsafe in concurrent rendering (#77, #100, #119). */
-      var dataChanged = this.options.animationData !== this.props.options.animationData;
+      /* Recreate the animation handle if the data, its remote path or the color
+         filters changed. Done here rather than in componentWillUpdate, which
+         React has deprecated and which is unsafe in concurrent rendering
+         (#77, #100, #119). */
+      var dataChanged = this.animationData !== this.props.options.animationData;
       var pathChanged = this.options.path !== this.props.options.path;
-      if (dataChanged || pathChanged) {
+      var colorFiltersChanged = !(0, _colorFilters.colorFiltersAreEqual)(this.colorFilters, this.props.colorFilters);
+      if (dataChanged || pathChanged || colorFiltersChanged) {
+        var currentFrame = this.anim ? this.anim.currentFrame : 0;
+        var wasPaused = this.anim ? this.anim.isPaused : true;
+        /* lottie-web cannot recolor a loaded animation, so a filter change has to
+           load the data again. Only a filter-only change restores the frame. */
+        var colorOnlyChange = colorFiltersChanged && !dataChanged && !pathChanged;
         this.deRegisterEvents(prevProps.eventListeners);
         this.destroy();
+        this.animationData = this.props.options.animationData;
+        this.colorFilters = this.props.colorFilters;
         this.options = _objectSpread(_objectSpread({}, this.options), this.props.options);
+        this.options.animationData = (0, _colorFilters.applyColorFilters)(this.props.options.animationData, this.props.colorFilters);
         this.anim = _lottieWeb["default"].loadAnimation(this.options);
         this.registerEvents(this.props.eventListeners);
+
+        /* Keep the frame and playback state so a theme change does not restart
+           a paused or half-played animation. */
+        if (colorOnlyChange) {
+          if (this.props.segments) this.anim.playSegments(this.props.segments, true);
+          if (Number.isFinite(currentFrame)) this.anim.goToAndStop(currentFrame, true);
+          if (!wasPaused) this.anim.play();
+        }
       }
 
       /* Only drive playback when a playback prop asks for it. Re-rendering used
@@ -275,6 +307,10 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
 Lottie.propTypes = {
   eventListeners: _propTypes["default"].arrayOf(_propTypes["default"].object),
   options: _propTypes["default"].object.isRequired,
+  colorFilters: _propTypes["default"].arrayOf(_propTypes["default"].shape({
+    keypath: _propTypes["default"].string.isRequired,
+    color: _propTypes["default"].string.isRequired
+  })),
   height: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   width: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   isStopped: _propTypes["default"].bool,
@@ -292,6 +328,7 @@ Lottie.propTypes = {
 };
 Lottie.defaultProps = {
   eventListeners: [],
+  colorFilters: [],
   isStopped: false,
   isPaused: false,
   speed: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lottie",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "funding": "https://opencollective.com/react-lottie",
   "description": "lottie animation view for React",
   "repository": {
@@ -51,7 +51,8 @@
     "react": ">=16.8.0"
   },
   "overrides": {
-    "cheerio": "1.0.0-rc.12"
+    "cheerio": "1.0.0-rc.12",
+    "minimatch@^10.2.2": "11.0.4"
   },
   "resolutions": {
     "cheerio": "1.0.0-rc.12"