0
# Animations & Effects
1
2
Animation and visual effect components that bring Material Design motion to life. These components include screen transitions, hero animations, ripple effects, elevation behaviors, and other motion elements that enhance user experience through smooth, meaningful animations.
3
4
## Capabilities
5
6
### Screen Transitions
7
8
Transition animations for screen changes and navigation flow.
9
10
```python { .api }
11
class MDFadeSlideTransition:
12
"""
13
Fade slide transition for screen manager.
14
15
Combines fade and slide animations for smooth screen transitions
16
with Material Design motion principles.
17
"""
18
direction: str # Transition direction: "left", "right", "up", "down"
19
duration: float # Transition duration in seconds
20
21
def start(self, instance_screen_manager):
22
"""Start the transition animation."""
23
24
def stop(self, instance_screen_manager):
25
"""Stop the transition animation."""
26
27
class MDSlideTransition:
28
"""
29
Slide transition for screen manager.
30
31
Pure slide animation for screen transitions with configurable
32
direction and timing.
33
"""
34
direction: str # Slide direction: "left", "right", "up", "down"
35
duration: float # Transition duration in seconds
36
37
class MDSwapTransition:
38
"""
39
Swap transition for screen manager.
40
41
Swap animation that flips between screens with a rotation effect.
42
"""
43
duration: float # Transition duration in seconds
44
```
45
46
### Hero Animations
47
48
Hero animations for smooth element transitions between screens.
49
50
```python { .api }
51
class MDHeroFrom:
52
"""
53
Hero animation source widget.
54
55
Marks a widget as the source of a hero animation that will
56
smoothly transition to a destination widget on another screen.
57
"""
58
tag: str # Unique identifier linking source to destination
59
60
# Animation properties
61
duration: float # Animation duration in seconds
62
transition: str # Animation transition type
63
64
def start_hero_animation(self):
65
"""Start the hero animation to destination."""
66
67
class MDHeroTo:
68
"""
69
Hero animation destination widget.
70
71
Marks a widget as the destination of a hero animation from
72
a source widget on another screen.
73
"""
74
tag: str # Unique identifier linking to source widget
75
76
# Animation properties
77
duration: float # Animation duration in seconds
78
transition: str # Animation transition type
79
80
def complete_hero_animation(self):
81
"""Complete the hero animation from source."""
82
```
83
84
### Ripple Effects
85
86
Touch feedback effects that provide visual confirmation of user interactions.
87
88
```python { .api }
89
class CircularRippleBehavior:
90
"""
91
Circular ripple effect behavior.
92
93
Mixin behavior that adds circular ripple effects to widgets
94
when touched, following Material Design interaction feedback.
95
"""
96
ripple_rad_default: float # Default ripple radius
97
ripple_color: str | list # Ripple color
98
ripple_alpha: float # Ripple opacity (0-1)
99
ripple_scale: float # Ripple scale factor
100
ripple_duration_in_slow: float # Slow ripple duration
101
ripple_duration_in_fast: float # Fast ripple duration
102
ripple_duration_out: float # Ripple fade out duration
103
104
# Ripple behavior
105
ripple_func_in: str # Animation function for ripple in
106
ripple_func_out: str # Animation function for ripple out
107
108
def lay_canvas_instructions(self):
109
"""Set up canvas instructions for ripple rendering."""
110
111
def start_ripple(self):
112
"""Start the ripple animation."""
113
114
def finish_ripple(self):
115
"""Finish the ripple animation."""
116
117
class RectangularRippleBehavior:
118
"""
119
Rectangular ripple effect behavior.
120
121
Mixin behavior that adds rectangular ripple effects to widgets,
122
typically used for rectangular buttons and cards.
123
"""
124
ripple_color: str | list # Ripple color
125
ripple_alpha: float # Ripple opacity (0-1)
126
ripple_scale: float # Ripple scale factor
127
ripple_duration_in: float # Ripple animation in duration
128
ripple_duration_out: float # Ripple animation out duration
129
130
# Ripple positioning
131
ripple_func_in: str # Animation function for ripple in
132
ripple_func_out: str # Animation function for ripple out
133
```
134
135
### Elevation Behaviors
136
137
Shadow and elevation effects that create depth and hierarchy.
138
139
```python { .api }
140
class CircularElevationBehavior:
141
"""
142
Circular elevation behavior for round widgets.
143
144
Provides elevation shadows for circular widgets like FABs
145
with appropriate shadow rendering.
146
"""
147
elevation: float # Elevation level (0-24)
148
shadow_radius: float # Shadow blur radius
149
shadow_softness: float # Shadow edge softness
150
shadow_offset: list # Shadow offset [x, y]
151
shadow_color: str | list # Shadow color
152
153
def update_elevation(self, elevation: float):
154
"""Update widget elevation level."""
155
156
class RectangularElevationBehavior:
157
"""
158
Rectangular elevation behavior for rectangular widgets.
159
160
Provides elevation shadows for rectangular widgets like cards
161
and buttons with proper shadow geometry.
162
"""
163
elevation: float # Elevation level (0-24)
164
shadow_radius: float # Shadow blur radius
165
shadow_softness: float # Shadow edge softness
166
shadow_offset: list # Shadow offset [x, y]
167
shadow_color: str | list # Shadow color
168
169
class RoundedRectangularElevationBehavior:
170
"""
171
Rounded rectangular elevation behavior.
172
173
Elevation behavior for widgets with rounded corners,
174
providing appropriate shadow rendering for rounded rectangles.
175
"""
176
elevation: float # Elevation level (0-24)
177
radius: list # Corner radius [top-left, top-right, bottom-right, bottom-left]
178
shadow_radius: float # Shadow blur radius
179
shadow_softness: float # Shadow edge softness
180
181
class CommonElevationBehavior:
182
"""
183
Common elevation behavior with shared functionality.
184
185
Base behavior providing common elevation properties
186
and methods for all elevation behaviors.
187
"""
188
elevation: float # Elevation level (0-24)
189
190
def set_elevation(self, elevation: float):
191
"""Set widget elevation level."""
192
193
class FakeCircularElevationBehavior:
194
"""
195
Fake circular elevation behavior.
196
197
Lightweight elevation effect that simulates shadows
198
without heavy rendering for performance optimization.
199
"""
200
elevation: float # Elevation level
201
shadow_softness: float # Shadow softness
202
203
class FakeRectangularElevationBehavior:
204
"""
205
Fake rectangular elevation behavior.
206
207
Lightweight elevation effect for rectangular widgets
208
with optimized rendering performance.
209
"""
210
elevation: float # Elevation level
211
shadow_softness: float # Shadow softness
212
```
213
214
### Animation Behaviors
215
216
Reusable animation behaviors for common motion patterns.
217
218
```python { .api }
219
class MagicBehavior:
220
"""
221
Magic animation behavior.
222
223
Provides magical transition effects and animations
224
for special interaction patterns.
225
"""
226
magic_speed: float # Animation speed
227
228
def grow(self):
229
"""Grow animation effect."""
230
231
def shrink(self):
232
"""Shrink animation effect."""
233
234
class RotateBehavior:
235
"""
236
Rotation animation behavior.
237
238
Mixin behavior that adds rotation capabilities to widgets
239
with smooth animation support.
240
"""
241
rotate_value_angle: float # Current rotation angle
242
rotate_value_axis: tuple # Rotation axis (x, y, z)
243
244
def start_rotation(self, angle: float, duration: float = 1.0):
245
"""
246
Start rotation animation.
247
248
Args:
249
angle (float): Target rotation angle in degrees
250
duration (float): Animation duration in seconds
251
"""
252
253
def stop_rotation(self):
254
"""Stop rotation animation."""
255
256
class ScaleBehavior:
257
"""
258
Scale animation behavior.
259
260
Mixin behavior that adds scaling capabilities to widgets
261
with smooth scale transitions.
262
"""
263
scale_value_x: float # X-axis scale factor
264
scale_value_y: float # Y-axis scale factor
265
scale_value_z: float # Z-axis scale factor
266
267
def start_scale(self, scale: float, duration: float = 1.0):
268
"""
269
Start scale animation.
270
271
Args:
272
scale (float): Target scale factor
273
duration (float): Animation duration in seconds
274
"""
275
276
def stop_scale(self):
277
"""Stop scale animation."""
278
279
class StencilBehavior:
280
"""
281
Stencil animation behavior.
282
283
Provides stencil-based animation effects for masking
284
and reveal animations.
285
"""
286
287
def apply_stencil(self):
288
"""Apply stencil effect."""
289
290
def remove_stencil(self):
291
"""Remove stencil effect."""
292
```
293
294
### Touch and Hover Behaviors
295
296
Interactive behaviors that respond to user input with animations.
297
298
```python { .api }
299
class TouchBehavior:
300
"""
301
Touch behavior for handling touch interactions.
302
303
Provides enhanced touch handling with animation feedback
304
and gesture recognition.
305
"""
306
touch_color: str | list # Touch feedback color
307
308
def on_touch_down(self, touch):
309
"""Handle touch down with animation."""
310
311
def on_touch_move(self, touch):
312
"""Handle touch move with feedback."""
313
314
def on_touch_up(self, touch):
315
"""Handle touch up with animation."""
316
317
class HoverBehavior:
318
"""
319
Hover behavior for desktop interactions.
320
321
Provides hover state animations and effects for
322
desktop applications with mouse input.
323
"""
324
hover_color: str | list # Hover state color
325
326
def on_enter(self):
327
"""Handle mouse enter with animation."""
328
329
def on_leave(self):
330
"""Handle mouse leave with animation."""
331
```
332
333
### Tap Target View
334
335
Tutorial and onboarding animations that highlight UI elements.
336
337
```python { .api }
338
class MDTapTargetView:
339
"""
340
Material Design tap target view.
341
342
Creates animated tutorial overlays that highlight specific
343
UI elements and provide contextual information for user onboarding.
344
"""
345
# Target widget
346
widget: object # Widget to highlight
347
348
# Content
349
title_text: str # Tap target title
350
description_text: str # Tap target description
351
widget_position: str # Target widget position: "left", "right", "top", "bottom", "center"
352
353
# Visual styling
354
outer_circle_color: str | list # Outer circle color
355
target_circle_color: str | list # Target circle color
356
title_text_color: str | list # Title text color
357
description_text_color: str | list # Description text color
358
359
# Animation
360
outer_circle_alpha: float # Outer circle opacity
361
target_radius: float # Target circle radius
362
363
# Behavior
364
cancelable: bool # Allow dismissing by tapping outside
365
366
def start(self):
367
"""Start the tap target animation."""
368
369
def stop(self):
370
"""Stop and hide the tap target view."""
371
372
def on_target_click(self):
373
"""Called when target area is clicked."""
374
375
def on_target_cancel(self):
376
"""Called when tap target is cancelled."""
377
```
378
379
## Usage Examples
380
381
### Screen Transitions
382
383
```python
384
from kivymd.uix.screenmanager import MDScreenManager
385
from kivymd.uix.screen import MDScreen
386
from kivymd.uix.transition import MDFadeSlideTransition, MDSlideTransition
387
388
class MyApp(MDApp):
389
def build(self):
390
# Create screen manager with custom transition
391
sm = MDScreenManager(
392
transition=MDFadeSlideTransition(
393
direction="left",
394
duration=0.3
395
)
396
)
397
398
# Create screens
399
screen1 = MDScreen(name="screen1")
400
screen2 = MDScreen(name="screen2")
401
402
# Add screens
403
sm.add_widget(screen1)
404
sm.add_widget(screen2)
405
406
return sm
407
408
def switch_to_slide_transition(self):
409
"""Switch to slide transition."""
410
self.root.transition = MDSlideTransition(
411
direction="right",
412
duration=0.4
413
)
414
```
415
416
### Hero Animations
417
418
```python
419
from kivymd.uix.hero import MDHeroFrom, MDHeroTo
420
from kivymd.uix.button import MDIconButton
421
from kivymd.uix.card import MDCard
422
423
class SourceScreen(MDScreen):
424
def build(self):
425
# Hero source - small FAB
426
hero_from = MDHeroFrom(
427
tag="fab_hero",
428
size_hint=(None, None),
429
size=("56dp", "56dp"),
430
pos_hint={"center_x": 0.1, "center_y": 0.1}
431
)
432
433
fab = MDIconButton(
434
icon="plus",
435
theme_icon_color="Custom",
436
icon_color="white",
437
md_bg_color="primary",
438
on_release=self.go_to_destination
439
)
440
441
hero_from.add_widget(fab)
442
return hero_from
443
444
def go_to_destination(self, instance):
445
"""Navigate to destination screen."""
446
self.manager.current = "destination"
447
448
class DestinationScreen(MDScreen):
449
def build(self):
450
# Hero destination - large card
451
hero_to = MDHeroTo(
452
tag="fab_hero",
453
size_hint=(0.8, 0.6),
454
pos_hint={"center_x": 0.5, "center_y": 0.5}
455
)
456
457
card = MDCard(
458
md_bg_color="primary",
459
elevation=8,
460
radius=[16, 16, 16, 16]
461
)
462
463
hero_to.add_widget(card)
464
return hero_to
465
```
466
467
### Ripple Effects
468
469
```python
470
from kivymd.uix.button import MDRaisedButton
471
from kivymd.uix.behaviors import CircularRippleBehavior
472
from kivymd.uix.card import MDCard
473
474
class RippleCard(MDCard, CircularRippleBehavior):
475
"""Card with ripple effect."""
476
477
def __init__(self, **kwargs):
478
super().__init__(**kwargs)
479
self.ripple_color = [0.2, 0.6, 1, 0.3] # Blue ripple
480
self.ripple_alpha = 0.3
481
self.ripple_scale = 2.0
482
483
class MyApp(MDApp):
484
def build(self):
485
layout = MDBoxLayout(
486
orientation="vertical",
487
spacing="16dp",
488
padding="16dp"
489
)
490
491
# Button with default ripple
492
button = MDRaisedButton(
493
text="Default Ripple",
494
pos_hint={"center_x": 0.5}
495
)
496
497
# Card with custom ripple
498
ripple_card = RippleCard(
499
size_hint=(0.8, None),
500
height="100dp",
501
pos_hint={"center_x": 0.5},
502
elevation=4,
503
md_bg_color="surface"
504
)
505
506
layout.add_widget(button)
507
layout.add_widget(ripple_card)
508
509
return layout
510
```
511
512
### Elevation Effects
513
514
```python
515
from kivymd.uix.card import MDCard
516
from kivymd.uix.behaviors import RectangularElevationBehavior
517
from kivymd.uix.button import MDRaisedButton
518
519
class ElevatedCard(MDCard):
520
"""Card with animated elevation."""
521
522
def __init__(self, **kwargs):
523
super().__init__(**kwargs)
524
self.elevation = 2
525
self.bind(on_touch_down=self.elevate_on_touch)
526
self.bind(on_touch_up=self.restore_elevation)
527
528
def elevate_on_touch(self, instance, touch):
529
"""Increase elevation on touch."""
530
if self.collide_point(*touch.pos):
531
Animation(elevation=8, duration=0.1).start(self)
532
533
def restore_elevation(self, instance, touch):
534
"""Restore normal elevation."""
535
Animation(elevation=2, duration=0.2).start(self)
536
537
class MyApp(MDApp):
538
def build(self):
539
layout = MDBoxLayout(
540
orientation="vertical",
541
spacing="24dp",
542
padding="16dp"
543
)
544
545
# Cards with different elevations
546
elevations = [2, 4, 8, 16]
547
548
for elev in elevations:
549
card = ElevatedCard(
550
size_hint=(0.8, None),
551
height="80dp",
552
pos_hint={"center_x": 0.5},
553
elevation=elev,
554
md_bg_color="surface"
555
)
556
557
# Add label showing elevation
558
label = MDLabel(
559
text=f"Elevation: {elev}",
560
halign="center",
561
theme_text_color="Primary"
562
)
563
card.add_widget(label)
564
565
layout.add_widget(card)
566
567
return layout
568
```
569
570
### Animation Behaviors
571
572
```python
573
from kivymd.uix.behaviors import RotateBehavior, ScaleBehavior
574
from kivymd.uix.button import MDIconButton
575
from kivy.animation import Animation
576
577
class AnimatedButton(MDIconButton, RotateBehavior, ScaleBehavior):
578
"""Button with rotation and scale animations."""
579
580
def __init__(self, **kwargs):
581
super().__init__(**kwargs)
582
self.bind(on_release=self.animate)
583
584
def animate(self, instance):
585
"""Trigger animations on button press."""
586
# Rotate 360 degrees
587
anim_rotate = Animation(
588
rotate_value_angle=360,
589
duration=1.0
590
)
591
592
# Scale up then down
593
anim_scale_up = Animation(
594
scale_value_x=1.5,
595
scale_value_y=1.5,
596
duration=0.2
597
)
598
anim_scale_down = Animation(
599
scale_value_x=1.0,
600
scale_value_y=1.0,
601
duration=0.2
602
)
603
604
# Chain animations
605
anim_scale = anim_scale_up + anim_scale_down
606
607
# Start animations
608
anim_rotate.start(self)
609
anim_scale.start(self)
610
611
class MyApp(MDApp):
612
def build(self):
613
return AnimatedButton(
614
icon="star",
615
pos_hint={"center_x": 0.5, "center_y": 0.5},
616
theme_icon_color="Custom",
617
icon_color="gold"
618
)
619
```
620
621
### Tap Target Tutorial
622
623
```python
624
from kivymd.uix.taptargetview import MDTapTargetView
625
from kivymd.uix.button import MDFloatingActionButton
626
627
class MyApp(MDApp):
628
def build(self):
629
layout = MDBoxLayout()
630
631
# FAB that will be highlighted
632
self.fab = MDFloatingActionButton(
633
icon="plus",
634
pos_hint={"center_x": 0.8, "center_y": 0.2},
635
on_release=self.fab_pressed
636
)
637
638
layout.add_widget(self.fab)
639
640
# Show tutorial after a delay
641
Clock.schedule_once(self.show_tutorial, 2)
642
643
return layout
644
645
def show_tutorial(self, dt):
646
"""Show tap target tutorial."""
647
tap_target = MDTapTargetView(
648
widget=self.fab,
649
title_text="Add New Item",
650
description_text="Tap this button to create a new item in your list. You can customize the item details after creation.",
651
widget_position="left_top",
652
title_text_color=[1, 1, 1, 1],
653
description_text_color=[0.9, 0.9, 0.9, 1],
654
outer_circle_color=[0.2, 0.6, 1, 0.8],
655
target_circle_color=[1, 1, 1, 1],
656
cancelable=True
657
)
658
659
tap_target.start()
660
661
def fab_pressed(self, instance):
662
"""Handle FAB press."""
663
print("FAB pressed - tutorial completed!")
664
```
665
666
### Complex Animation Sequence
667
668
```python
669
from kivy.animation import Animation
670
from kivymd.uix.card import MDCard
671
from kivymd.uix.label import MDLabel
672
673
class AnimatedCard(MDCard):
674
"""Card with complex animation sequence."""
675
676
def __init__(self, **kwargs):
677
super().__init__(**kwargs)
678
self.elevation = 2
679
self.setup_animations()
680
681
def setup_animations(self):
682
"""Set up animation sequence."""
683
# Animation sequence: fade in -> scale up -> bounce -> fade out
684
self.fade_in = Animation(
685
opacity=1,
686
duration=0.5
687
)
688
689
self.scale_up = Animation(
690
size_hint=(0.9, 0.4),
691
duration=0.3
692
)
693
694
self.bounce = Animation(
695
pos_hint={"center_y": 0.6},
696
duration=0.2
697
) + Animation(
698
pos_hint={"center_y": 0.5},
699
duration=0.2
700
)
701
702
self.fade_out = Animation(
703
opacity=0,
704
duration=0.5
705
)
706
707
def start_animation_sequence(self):
708
"""Start the complete animation sequence."""
709
# Chain animations
710
sequence = self.fade_in + self.scale_up + self.bounce
711
sequence.bind(on_complete=self.on_animation_complete)
712
sequence.start(self)
713
714
def on_animation_complete(self, animation, widget):
715
"""Handle animation completion."""
716
Clock.schedule_once(lambda dt: self.fade_out.start(self), 2)
717
718
class MyApp(MDApp):
719
def build(self):
720
layout = MDBoxLayout()
721
722
# Create animated card
723
card = AnimatedCard(
724
size_hint=(0.6, 0.3),
725
pos_hint={"center_x": 0.5, "center_y": 0.5},
726
opacity=0,
727
md_bg_color="primary"
728
)
729
730
label = MDLabel(
731
text="Animated Card",
732
halign="center",
733
theme_text_color="Custom",
734
text_color=[1, 1, 1, 1]
735
)
736
card.add_widget(label)
737
738
# Start animation after delay
739
Clock.schedule_once(
740
lambda dt: card.start_animation_sequence(),
741
1
742
)
743
744
layout.add_widget(card)
745
return layout
746
```