feat: add layout (fit/align) prop to DotLottie

Expose a layout prop ({ fit, align }) on the DotLottie component and forward
it to the native iOS and Android players and the web implementation, with
shared types and an example demonstrating the fit modes.

Author: theashraf

README.md

@@ -198,6 +198,17 @@ const styles = StyleSheet.create({
 | `marker`                | `string`                    | `undefined`   | Specifies a marker to use for playback.                                |
 | `themeId`               | `string`                    | `undefined`   | The theme ID to apply to the animation.                                |
 | `stateMachineId`        | `string`                    | `undefined`   | The ID of the state machine to load and start automatically.           |
+| `layout`                | `{ fit?: Fit; align?: [number, number] }` | `undefined`   | Controls how the animation fits its container. `fit`: `contain` (default), `cover`, `fill`, `fit-width`, `fit-height`, `none`. `align`: crop anchor, each `0..1`, default `[0.5, 0.5]`. |
+
+**Example — fill the container and crop the overflow:**
+
+```tsx
+<DotLottie
+  source={require('./animation.lottie')}
+  style={{ flex: 1 }}
+  layout={{ fit: 'cover' }}
+/>
+```
 
 ### Methods
 

android/src/main/java/com/dotlottiereactnative/DotlottieReactNativeView.kt

@@ -7,9 +7,11 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.ComposeView
+import com.dotlottie.dlplayer.Fit
 import com.dotlottie.dlplayer.Mode
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.events.RCTEventEmitter
@@ -33,6 +35,8 @@ class DotlottieReactNativeView(context: ThemedReactContext) : FrameLayout(contex
   private var segment: Pair<Float, Float>? = null
   private var playMode: Mode = Mode.FORWARD
   private var stateMachineId: String? = null
+  private var layoutFit: Fit = Fit.CONTAIN
+  private var layoutAlign: Pair<Float, Float> = Pair(0.5f, 0.5f)
   private var useOpenGLRenderer: Boolean = false
   private var rendererLocked: Boolean = false
   var dotLottieController: DotLottieController = DotLottieController()
@@ -286,6 +290,25 @@ class DotlottieReactNativeView(context: ThemedReactContext) : FrameLayout(contex
     dotLottieController.resize(width, height)
   }
 
+  fun setLayout(map: ReadableMap?) {
+    layoutFit = when (if (map?.hasKey("fit") == true) map.getString("fit") else null) {
+      "cover" -> Fit.COVER
+      "fill" -> Fit.FILL
+      "fit-width" -> Fit.FIT_WIDTH
+      "fit-height" -> Fit.FIT_HEIGHT
+      "none" -> Fit.NONE
+      else -> Fit.CONTAIN
+    }
+    layoutAlign = if (map?.hasKey("align") == true) {
+      map.getArray("align")?.takeIf { it.size() == 2 }
+        ?.let { Pair(it.getDouble(0).toFloat(), it.getDouble(1).toFloat()) }
+        ?: Pair(0.5f, 0.5f)
+    } else {
+      Pair(0.5f, 0.5f)
+    }
+    dotLottieController.setLayout(layoutFit, layoutAlign)
+  }
+
   fun getTotalFrames(): Float {
     return dotLottieController.totalFrames
   }

android/src/main/java/com/dotlottiereactnative/DotlottieReactNativeViewManager.kt

@@ -2,6 +2,7 @@ package com.dotlottiereactnative
 
 import com.dotlottie.dlplayer.Mode
 import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.common.annotations.internal.InteropLegacyArchitecture
 import com.facebook.react.uimanager.SimpleViewManager
 import com.facebook.react.uimanager.ThemedReactContext
@@ -39,7 +40,6 @@ class DotlottieReactNativeViewManager : SimpleViewManager<DotlottieReactNativeVi
             COMMAND_SET_USE_FRAME_INTERPOLATION to COMMAND_SET_USE_FRAME_INTERPOLATION_ID,
             COMMAND_SET_SEGMENT to COMMAND_SET_SEGMENT_ID,
             COMMAND_SET_MARKER to COMMAND_SET_MARKER_ID,
-            COMMAND_SET_LAYOUT to COMMAND_SET_LAYOUT_ID,
             COMMAND_SET_THEME to COMMAND_SET_THEME_ID,
             COMMAND_LOAD_ANIMATION to COMMAND_LOAD_ANIMATION_ID,
     )
@@ -240,6 +240,11 @@ class DotlottieReactNativeViewManager : SimpleViewManager<DotlottieReactNativeVi
     view.setUseOpenGLRenderer(value == "gl")
   }
 
+  @ReactProp(name = "layout")
+  fun setLayout(view: DotlottieReactNativeView, value: ReadableMap?) {
+    view.setLayout(value)
+  }
+
   override fun onDropViewInstance(view: DotlottieReactNativeView) {
     super.onDropViewInstance(view)
     view.release()
@@ -314,9 +319,6 @@ class DotlottieReactNativeViewManager : SimpleViewManager<DotlottieReactNativeVi
     private const val COMMAND_SET_MARKER = "setMarker"
     private const val COMMAND_SET_MARKER_ID = 22
 
-    private const val COMMAND_SET_LAYOUT = "setLayout"
-    private const val COMMAND_SET_LAYOUT_ID = 23
-
     private const val COMMAND_SET_THEME = "setTheme"
     private const val COMMAND_SET_THEME_ID = 24
 

example/App.tsx

@@ -11,6 +11,7 @@ import { LifecycleExample } from './examples/LifecycleExample';
 import { StateMachineExample } from './examples/StateMachineExample';
 import { MultipleAnimationsTest } from './examples/MultipleAnimationsTest';
 import { SourceLoadingExample } from './examples/SourceLoadingExample';
+import { LayoutFitExample } from './examples/LayoutFitExample';
 
 type ExampleDescriptor = {
   key: string;
@@ -27,6 +28,13 @@ const EXAMPLES: ExampleDescriptor[] = [
       'Verifies local require() and remote URL sources render, incl. Android release builds.',
     Component: SourceLoadingExample,
   },
+  {
+    key: 'layout-fit',
+    title: 'Layout / fit (issue #64)',
+    description:
+      'Switch fit modes (contain, cover, fill, …) in a wide container to see filling vs cropping.',
+    Component: LayoutFitExample,
+  },
   {
     key: 'multiple-animations',
     title: 'Multiple Animations Test',

example/examples/LayoutFitExample.tsx

@@ -0,0 +1,106 @@
+import { useState } from 'react';
+import {
+  ScrollView,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { DotLottie, type Fit } from '@lottiefiles/dotlottie-react-native';
+
+const FITS: Fit[] = [
+  'contain',
+  'cover',
+  'fill',
+  'fit-width',
+  'fit-height',
+  'none',
+];
+
+export function LayoutFitExample() {
+  const [fit, setFit] = useState<Fit>('cover');
+
+  return (
+    <ScrollView contentContainerStyle={styles.container}>
+      <Text style={styles.hint}>
+        The stage below is intentionally wide (2:1). Switch the fit mode and
+        watch the square animation fill, crop, stretch, or letterbox it.
+      </Text>
+
+      <View style={styles.fitRow}>
+        {FITS.map((option) => (
+          <TouchableOpacity
+            key={option}
+            style={[styles.chip, fit === option && styles.chipActive]}
+            onPress={() => setFit(option)}
+          >
+            <Text
+              style={[styles.chipText, fit === option && styles.chipTextActive]}
+            >
+              {option}
+            </Text>
+          </TouchableOpacity>
+        ))}
+      </View>
+
+      <View style={styles.stage}>
+        <DotLottie
+          source={require('../assets/star-rating.lottie')}
+          style={styles.animation}
+          autoplay
+          loop
+          layout={{ fit }}
+        />
+      </View>
+
+      <Text style={styles.current}>{`layout={{ fit: '${fit}' }}`}</Text>
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 16,
+    gap: 16,
+  },
+  hint: {
+    fontSize: 14,
+    color: '#555',
+  },
+  fitRow: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: 8,
+  },
+  chip: {
+    paddingHorizontal: 12,
+    paddingVertical: 6,
+    borderRadius: 16,
+    backgroundColor: '#e6e6e6',
+  },
+  chipActive: {
+    backgroundColor: '#1a7f37',
+  },
+  chipText: {
+    fontSize: 13,
+    color: '#333',
+  },
+  chipTextActive: {
+    color: '#fff',
+    fontWeight: '600',
+  },
+  stage: {
+    width: '100%',
+    aspectRatio: 2,
+    backgroundColor: '#f6f8fa',
+    borderRadius: 8,
+    overflow: 'hidden',
+  },
+  animation: {
+    flex: 1,
+  },
+  current: {
+    fontSize: 13,
+    color: '#888',
+  },
+});

example/ios/Podfile.lock

@@ -1,6 +1,6 @@
 PODS:
   - boost (1.84.0)
-  - dotlottie-react-native (0.9.1):
+  - dotlottie-react-native (0.9.3):
     - boost
     - DoubleConversion
     - fast_float
@@ -2513,7 +2513,7 @@ EXTERNAL SOURCES:
 
 SPEC CHECKSUMS:
   boost: 7e761d76ca2ce687f7cc98e698152abd03a18f90
-  dotlottie-react-native: d1737769a6a7abf1e5b414987223b9db7201932d
+  dotlottie-react-native: 8e628ab741e15d7f925557255a2639a2a4a91e54
   DoubleConversion: cb417026b2400c8f53ae97020b2be961b59470cb
   fast_float: b32c788ed9c6a8c584d114d0047beda9664e7cc6
   FBLazyVector: 941bef1c8eeabd9fe1f501e30a5220beee913886

ios/DotlottieReactNativeViewManager.m

@@ -35,6 +35,7 @@ @interface RCT_EXTERN_MODULE(DotlottieReactNativeViewManager, RCTViewManager)
 RCT_EXPORT_VIEW_PROPERTY(playMode, NSNumber)
 RCT_EXPORT_VIEW_PROPERTY(useFrameInterpolation, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(stateMachineId, NSString)
+RCT_EXPORT_VIEW_PROPERTY(layout, NSDictionary)
 RCT_EXPORT_VIEW_PROPERTY(onPlay, RCTDirectEventBlock)
 RCT_EXPORT_VIEW_PROPERTY(onPause, RCTDirectEventBlock)
 RCT_EXPORT_VIEW_PROPERTY(onStop, RCTDirectEventBlock)

ios/DotlottieReactNativeViewManager.swift

@@ -13,6 +13,7 @@ import SwiftUI
   @Published var marker: NSString = ""
   @Published var themeId: NSString = ""
   @Published var stateMachineId: NSString = ""
+  @Published var layoutConfig: NSDictionary? = nil
   @Published var onPlay: RCTDirectEventBlock = {_ in }
   @Published var onLoad: RCTDirectEventBlock = {_ in }
   @Published var onLoadError: RCTDirectEventBlock = {_ in }
@@ -82,6 +83,28 @@ import SwiftUI
     _ = animation.stateMachineSubscribe(stateMachineObserver)
   }
 
+  private func buildLayout() -> DotLottie.Layout? {
+    guard let dict = layoutConfig else { return nil }
+    let fitString = (dict["fit"] as? String) ?? "contain"
+    let fit: Fit = {
+      switch fitString {
+      case "cover": return .cover
+      case "fill": return .fill
+      case "fit-width": return .fitWidth
+      case "fit-height": return .fitHeight
+      case "none": return .none
+      default: return .contain
+      }
+    }()
+    var alignX: Float = 0.5
+    var alignY: Float = 0.5
+    if let alignArr = dict["align"] as? [NSNumber], alignArr.count == 2 {
+      alignX = Float(truncating: alignArr[0])
+      alignY = Float(truncating: alignArr[1])
+    }
+    return DotLottie.Layout(fit: fit, alignX: alignX, alignY: alignY)
+  }
+
    func buildAnimationConfig() -> AnimationConfig {
      // Convert playMode to Mode enum
      let mode: Mode = {
@@ -113,7 +136,7 @@ import SwiftUI
        backgroundColor: nil,
        width: nil,  // Use default
        height: nil,  // Use default
-       layout: nil,  // Use default
+       layout: buildLayout(),
        marker: marker != "" ? String(marker) : "",
        themeId: themeId != "" ? String(themeId) : "",
        stateMachineId: stateMachineId != "" ? String(stateMachineId) : ""
@@ -721,6 +744,18 @@ class DotlottieReactNativeView: UIView {
     }
   }
 
+  @objc var layout: NSDictionary? {
+    didSet {
+      performIfActive {
+        dataStore.layoutConfig = layout
+        // Recreate so the new layout applies whether or not the animation exists
+        // yet. (The SDK also exposes a runtime setLayout if a no-reload path is
+        // preferred later.)
+        scheduleAnimationUpdate()
+      }
+    }
+  }
+
   @objc var stateMachineId: NSString = "" {
     didSet {
       performIfActive {

package.json

@@ -127,6 +127,7 @@
   "packageManager": "yarn@3.6.1",
   "jest": {
     "preset": "react-native",
+    "passWithNoTests": true,
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"

src/DotLottie.tsx

@@ -16,6 +16,9 @@ import {
   type NativeSyntheticEvent,
 } from 'react-native';
 import { parseSource } from './utils';
+import type { Layout } from './layout';
+
+export type { Fit, Align, Layout } from './layout';
 
 const LINKING_ERROR =
   `The package '@lottiefiles/dotlottie-react-native' doesn't seem to be linked. Make sure: \n\n` +
@@ -79,6 +82,7 @@ interface DotlottieNativeProps {
   useFrameInterpolation?: boolean;
   stateMachineId?: string;
   renderer?: Renderer;
+  layout?: Layout;
   style: ViewStyle;
   ref?: MutableRefObject<any>;
   onLoad?: () => void;
@@ -149,6 +153,7 @@ interface DotlottieReactNativeProps {
   useFrameInterpolation?: boolean;
   stateMachineId?: string;
   renderer?: Renderer;
+  layout?: Layout;
   style: ViewStyle;
   ref?: MutableRefObject<any>;
   onLoad?: () => void;