Table Of Contents

LottieWidget

A Kivy widget for displaying and controlling Lottie animations.

Features

  • Lottie JSON loading from source (local file path)

  • Playback control via state ('play', 'pause', 'stop'), seek(), and progress (0.0-1.0 normalised position)

  • Standard image display properties: fit_mode, color, norm_image_size

  • Runtime DOM manipulation

  • Segments and markers - divide an animation into named or custom ranges and play them independently: markers, play_segment(), play_marker()

  • Slot overrides - change colours, opacity, text, and images on named slots at runtime without reloading the file: slots, has_slot(), set_color(), set_opacity(), set_text(), set_image(), apply_slot(), reset_slot()

  • Rendering quality - tune the fidelity of blur and shadow effects: set_quality()

Basic usage

from kivy.uix.lottie import LottieWidget

w = LottieWidget(source='animation.json', size_hint=(None, None),
                 size=(400, 400), state='play')

KV:

LottieWidget:
    source: 'animation.json'
    fit_mode: 'contain'
    state: 'play'
    eos: 'loop'
    on_load: print('ready', self.duration, 'seconds')
    on_eos: print('loop!')

Slot colour override

w = LottieWidget(source='branded.json')
w.bind(on_load=lambda *a: w.set_color('brand_color', (0.2, 0.6, 1.0)))

Added in version 3.0.0.

class kivy.uix.lottie.LottieWidget(**kwargs)[source]

Bases: Widget

Widget that displays a Lottie animation.

The animation is rasterized to a Texture by the configured Lottie provider (kivy.core.lottie). The texture is shared with the canvas drawing instructions added by the KV rule in kivy/data/style.kv - the same rule that drives Image and SvgWidget.

All DOM manipulation methods delegate transparently to the underlying LottieBase provider.

apply_slot(slot_data)[source]

Apply a raw slot override from a JSON string and return the slot handle.

Prefer the typed helpers (set_color(), set_opacity(), set_text(), set_image()) for common cases. Use this method when you need to apply a slot structure that the helpers do not cover.

Parameters:

slot_data (str) – Slot override as a JSON string.

Returns:

Slot handle (pass to reset_slot() to remove), or None on failure or when no animation is loaded.

Return type:

int or None

color

Tint colour applied via the canvas Color instruction.

color is a ColorProperty and defaults to [1, 1, 1, 1] (opaque white - no tint).

duration

Total animation duration in seconds (read-only after load).

duration is a NumericProperty and defaults to 0.0.

eos

End-of-animation behaviour.

  • 'loop' - restart from the beginning (default).

  • 'stop' - halt and rewind to frame 0. Use this when the first frame is the natural idle state of the animation (e.g. a spinner that should disappear or reset when done).

  • 'pause' - halt and remain on the last frame. Use this for one-shot animations that end in a new visual state (e.g. a character settling into a new pose).

Both 'stop' and 'pause' cancel the playback clock; the only difference is whether the playhead rewinds to frame 0 ('stop') or stays at the final frame ('pause').

eos is an OptionProperty and defaults to 'loop'.

fit_mode

Scaling mode for display within the widget bounds.

Identical in meaning to fit_mode.

fit_mode is an OptionProperty and defaults to 'contain'.

get_norm_image_size()[source]

Return the display size of the animation after applying fit_mode.

Mirrors get_norm_image_size() exactly.

has_slot(slot_id)[source]

Return True if slot_id is present in the loaded animation.

Parameters:

slot_id (str) – Slot ID to check.

Return type:

bool

image_ratio

Aspect ratio of the current texture (width / height).

image_ratio is a read-only AliasProperty.

loaded

True once the animation has loaded successfully.

Use this as a guard before calling DOM manipulation methods:

if widget.loaded:
    widget.set_color('brand', (0.2, 0.6, 1.0))

loaded is a BooleanProperty and defaults to False.

property markers

List of marker names in the loaded animation.

Return type:

list[str]

norm_image_size

The portion of the widget area actually occupied by the animation after fit_mode geometry is applied.

norm_image_size is a read-only AliasProperty.

on_state(instance, value)[source]

Kivy property event - sync the provider whenever state changes.

play_marker(name)[source]

Restrict playback to the named marker range.

After the call, duration, total_frames, and position are updated to reflect the marker’s frame range so that progress reporting and EOS detection remain accurate.

Parameters:

name (str) – Marker name (see markers).

Raises:

ValueError – If the marker does not exist.

play_segment(begin, end)[source]

Restrict playback to the frame range [begin, end].

After the call, duration, total_frames, and position are updated to reflect the new segment so that progress reporting and EOS detection remain accurate.

Parameters:

  • begin (float) – First frame (inclusive).

  • end (float) – Last frame (inclusive).

position

Current playback position in seconds.

Setting this property seeks the animation.

position is a NumericProperty and defaults to 0.0.

progress

Normalised playback position in the range 0.0-1.0.

A computed view of position / duration. Setting it seeks the animation to the corresponding time. Useful for binding directly to a Slider:

Slider:
    min: 0
    max: 1
    value: anim.progress
    on_value: anim.progress = self.value

progress is an AliasProperty and defaults to 0.0.

refresh()[source]

Force an immediate re-render of the current frame.

reset_slot(slot_id=None)[source]

Remove a slot override or clear all overrides.

Parameters:

slot_id (str or None) – Slot ID string, or None to clear all.

seek(percent)[source]

Seek to percent (0.0-1.0) through the animation.

Parameters:

percent (float) – Position as a fraction of the total duration.

set_color(slot_id, color)[source]

Override the fill colour of a slot.

Parameters:

  • slot_id (str) – Slot ID.

  • color – (r, g, b) or (r, g, b, a) floats 0.0-1.0.

Returns:

Slot handle or None.

Return type:

int or None

set_image(slot_id, source)[source]

Override the image of an image slot.

Parameters:

  • slot_id (str) – Slot ID.

  • source (str) – Absolute path to the replacement image.

Returns:

Slot handle or None.

Return type:

int or None

set_opacity(slot_id, opacity)[source]

Override the opacity of a slot.

Parameters:

  • slot_id (str) – Slot ID.

  • opacity (float) – 0.0 (transparent) - 1.0 (opaque).

Returns:

Slot handle or None.

Return type:

int or None

set_quality(value)[source]

Set the rendering quality level (0-100).

Parameters:

value (int) – 0 = fastest, 100 = best.

set_text(slot_id, text)[source]

Override the text content of a text slot.

Parameters:

  • slot_id (str) – Slot ID.

  • text (str) – New text string.

Returns:

Slot handle or None.

Return type:

int or None

property slots

Frozenset of slot IDs in the loaded animation.

Return type:

frozenset[str]

source

Path to the Lottie JSON file.

Changing this property automatically loads the new animation.

source is a StringProperty and defaults to ''.

state

String, indicates whether to play, pause, or stop the animation:

# start playing immediately at construction
w = LottieWidget(source='anim.json', state='play')

# start later
w = LottieWidget(source='anim.json')
w.state = 'play'

state is an OptionProperty and defaults to 'stop'.

texture

Current rasterized Texture.

Updated on every on_frame event dispatched by the provider.

texture is an ObjectProperty and defaults to None.

texture_size

Pixel dimensions [w, h] of the current texture.

Updated whenever texture changes.

texture_size is a ListProperty and defaults to [0, 0].

total_frames

Total number of frames in the animation (read-only after load).

total_frames is a NumericProperty and defaults to 0.0.

« Layout ModalView »