Elevation

See also

Material Design spec, Elevation

Elevation is the relative distance between two surfaces along the z-axis.

To create an elevation effect, use the CommonElevationBehavior class. For example, let’s create a button with a rectangular elevation effect:

Declarative style with KVDeclarative python style

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import (
    RectangularRippleBehavior,
    BackgroundColorBehavior,
    CommonElevationBehavior,
)

KV = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    # With elevation effect
    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4.5
        shadow_offset: 0, 6

    # Without elevation effect
    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .4}
'''


class RectangularElevationButton(
    RectangularRippleBehavior,
    CommonElevationBehavior,
    ButtonBehavior,
    BackgroundColorBehavior,
):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "red"


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

Warning

If before the KivyMD 1.1.0 library version you used the elevation property with an average value of 12 for the shadow, then starting with the KivyMD 1.1.0 library version, the average value of the elevation property will be somewhere 4.

Similarly, create a circular button:

Declarative style with KVDeclarative python style

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior, CommonElevationBehavior
from kivymd.uix.floatlayout import MDFloatLayout

KV = '''
<CircularElevationButton>
    size_hint: None, None
    size: "100dp", "100dp"
    radius: self.size[0] / 2
    shadow_radius: self.radius[0]
    md_bg_color: "red"

    MDIcon:
        icon: "hand-heart"
        halign: "center"
        valign: "center"
        pos_hint: {"center_x": .5, "center_y": .5}
        size: root.size
        pos: root.pos
        font_size: root.size[0] * .6
        theme_text_color: "Custom"
        text_color: "white"


MDScreen:

    CircularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4
'''


class CircularElevationButton(
    CommonElevationBehavior,
    CircularRippleBehavior,
    ButtonBehavior,
    MDFloatLayout,
):
    pass


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

Animating the elevation

Declarative style with KVDeclarative python style

from kivy.animation import Animation
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior, RectangularRippleBehavior
from kivymd.uix.widget import MDWidget

KV = '''
MDScreen:

    ElevatedWidget:
        pos_hint: {'center_x': .5, 'center_y': .5}
        size_hint: None, None
        size: 100, 100
        md_bg_color: 0, 0, 1, 1
        elevation: 4
        radius: 18
'''


class ElevatedWidget(
    CommonElevationBehavior,
    RectangularRippleBehavior,
    ButtonBehavior,
    MDWidget,
):
    _elev = 0  # previous elevation value

    def on_press(self, *args):
        if not self._elev:
            self._elev = self.elevation
        Animation(elevation=self.elevation + 2, d=0.4).start(self)

    def on_release(self, *args):
        Animation.cancel_all(self, "elevation")
        Animation(elevation=self._elev, d=0.1).start(self)


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

API - kivymd.uix.behaviors.elevation

class kivymd.uix.behaviors.elevation.CommonElevationBehavior(**kwargs)

Common base class for rectangular and circular elevation behavior.

elevation

Elevation of the widget.

elevation is an BoundedNumericProperty and defaults to 0.

shadow_radius

Radius of the corners of the shadow.

New in version 1.1.0.

You don’t have to use this parameter. The radius of the elevation effect is calculated automatically one way or another based on the radius of the parent widget, for example:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDCard:
        radius: 12, 46, 12, 46
        size_hint: .5, .3
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 4
        shadow_softness: 8
        shadow_offset: (-2, 2)
'''


class Test(MDApp):
    def build(self):
        return Builder.load_string(KV)


Test().run()

Note

However, if you want to use this parameter, remember that the angle values for the radius of the Kivy widgets and the radius for the shader are different.

shadow_radius = ['top-right', 'bot-right', 'top-left', 'bot-left']
kivy_radius = ['top-left', 'top-right', 'bottom-right', 'bottom-left']

shadow_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

shadow_softness

Softness of the shadow.

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 6
        shadow_softness: 6

    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .4}
        elevation: 6
        shadow_softness: 12
'''


class RectangularElevationButton(CommonElevationBehavior, BackgroundColorBehavior):
    md_bg_color = [0, 0, 1, 1]


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

shadow_softness is an NumericProperty and defaults to 12.

shadow_softness_size

The value of the softness of the shadow.

New in version 1.1.0.

Since we can’t properly adjust the shadow_softness value and the elevation value, we added the shadow_softness_size attribute to control the shadow size.

MDCard:
    elevation: 4
    shadow_radius: 8

But if we need to increase the elevation value:

MDCard:
    elevation: 8
    shadow_radius: 16

… we will get a sharp dark shadow:

To soften the shadow, we need to use the shadow_softness value:

MDCard:
    elevation: 8
    shadow_radius: 16
    shadow_softness: 24

But this is still not the result we expected. But it’s still not the result we expected. And if we keep increasing the value of shadow_softness, then we won’t be able to change the result much:

We need to use the shadow_softness_size value if we have increased the elevation value and want to get the smoothness of the shadow:

MDCard:
    elevation: 8
    shadow_radius: 24
    shadow_softness: 56
    shadow_softness_size: 3.5

shadow_softness_size is an NumericProperty and defaults to 2.

shadow_offset

Offset of the shadow.

New in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "100dp", "100dp"


MDScreen:

    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 6
        shadow_radius: 18
        shadow_softness: 24
        shadow_offset: 12, 12
'''


class RectangularElevationButton(CommonElevationBehavior, BackgroundColorBehavior):
    md_bg_color = [0, 0, 1, 1]


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

RectangularElevationButton:
    shadow_offset: -12, 12

RectangularElevationButton:
    shadow_offset: -12, -12

RectangularElevationButton:
    shadow_offset: 12, -12

shadow_offset is an ListProperty and defaults to (0, 2).

shadow_color

Offset of the shadow.

New in version 1.1.0.

RectangularElevationButton:
    shadow_color: 0, 0, 1, .8

shadow_color is an ColorProperty and defaults to [0.4, 0.4, 0.4, 0.8].

widget_pos

get_shader_string(self)

set_shader_string(self, *args)

update_resolution(self)

on_shadow_color(self, instance, value)

on_shadow_radius(self, instance, value)

on_shadow_softness(self, instance, value)

on_elevation(self, instance, value)

on_shadow_offset(self, instance, value)

on_pos(self, *args)

on_size(self, *args)

on_opacity(self, instance, value: int | float)

Adjusts the transparency of the shadow according to the transparency of the widget.

on_radius(self, instance, value)

on_disabled(self, instance, value)

hide_elevation(self, hide: bool)

class kivymd.uix.behaviors.elevation.RectangularElevationBehavior(**kwargs)

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

class kivymd.uix.behaviors.elevation.CircularElevationBehavior(**kwargs)

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

class kivymd.uix.behaviors.elevation.RoundedRectangularElevationBehavior(**kwargs)

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

class kivymd.uix.behaviors.elevation.FakeRectangularElevationBehavior(**kwargs)

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

class kivymd.uix.behaviors.elevation.FakeCircularElevationBehavior(**kwargs)

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.