Elevation#

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

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevation-previous.png

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

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-effect.png

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:

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-elevation-effect.png

Animating the elevation#

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-animation-effect.gif

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-radius.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness.png

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
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness-step-1.png

But if we need to increase the elevation value:

MDCard:
    elevation: 8
    shadow_radius: 16

… we will get a sharp dark shadow:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness-step-2.png

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

MDCard:
    elevation: 8
    shadow_radius: 16
    shadow_softness: 24
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness-step-3.png

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:

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness-step-4.png

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
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness-step-5.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-1.png
RectangularElevationButton:
    shadow_offset: -12, 12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-2.png
RectangularElevationButton:
    shadow_offset: -12, -12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-3.png
RectangularElevationButton:
    shadow_offset: 12, -12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-4.png

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
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-color.png

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.