:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/loadingindicator/loadingindicator.py

LoadingIndicator
================

.. py:module:: kivymd.uix.loadingindicator.loadingindicator

.. autoapi-nested-parse::

   Components/LoadingIndicator
   ===========================

   .. seealso::

       `Material Design spec, Loading indicator <https://m3.material.io/components/loading-indicator/overview>`_
       `Shapes preview <https://github.com/T-Dynamos/materialshapes-python/tree/c48e367bd9e7ef3db95ea68bd2e3f8fd1fc976cb?tab=readme-ov-file#preview>`_

   .. rubric:: Loading indicators display the status of a process using continuous or sequential shape animations.

   - Used to represent indeterminate operations (no fixed end).
   - Each shape is based on Material 3 geometry guidelines.
   - Animations can cycle between multiple predefined shapes.


   Usage
   -----

   .. tabs::

       .. tab:: Declarative Python style with KV

           .. code-block:: python

               from kivy.clock import Clock
               from kivy.lang import Builder
               from kivymd.app import MDApp

               KV = '''
               MDScreen:
                   md_bg_color: app.theme_cls.surfaceColor
                   MDLoadingIndicator:
                       id: indicator
                       shape_size: dp(100)
               '''


               class ExampleApp(MDApp):

                   def build(self):
                       return Builder.load_string(KV)

                   def on_start(self):
                       # start the morphing animation
                       self.root.ids.indicator.start()

                       # print available shape names
                       print(self.root.ids.indicator.get_shape_names())

                       # optionally stop animation after 5 seconds
                       # Clock.schedule_once(self.root.ids.indicator.stop, 5)


               ExampleApp().run()

       .. tab:: Declarative Python style

           .. code-block:: python

               from kivymd.app import MDApp
               from kivymd.uix.screen import MDScreen
               from kivymd.uix.loadingindicator import MDLoadingIndicator

               class ExampleApp(MDApp):
                   def build(self):
                       return MDScreen(
                           MDLoadingIndicator(
                               id="indicator",
                               shape_size="100dp",
                           ),
                           md_bg_color=self.theme_cls.surfaceColor,
                       )

                   def on_start(self):
                       # start the morphing animation
                       self.root.children[0].start()

                       # print available shape names
                       print(self.root.children[0].get_shape_names())

                       # optionally stop animation after 5 seconds
                       # Clock.schedule_once(self.root.ids.indicator.stop, 5)

               ExampleApp().run()


   .. image:: https://github.com/user-attachments/assets/1a24f741-a710-4271-993b-5a335a284787
       :align: center


API - :mod:`kivymd.uix.loadingindicator.loadingindicator`
---------------------------------------------------------

.. py:class:: MDLoadingIndicator(*args, **kwargs)




   Implementation of a morphing and rotating loading indicator.

   For more information, see the
   :class:`~kivy.uix.anchorlayout.AnchorLayout` and
   :class:`~kivymd.uix.behaviors.RotateBehavior`
   classes documentation.

   .. py:attribute:: shape

      Current shape name displayed by the loading indicator.

      The shape corresponds to one of the predefined shapes available
      in the :class:`~materialshapes.kivy_widget.MaterialShape` library.

      You can view all available shape names using
      :meth:`get_shape_names`.

      :attr:`shape` is a :class:`~kivy.properties.StringProperty`
      and defaults to `'cookie12Sided'`.


   .. py:attribute:: shape_sequence

      Sequence of shape names through which the indicator cycles.

      Each shape in the list is morphed into the next one over time,
      looping continuously while the indicator is active.

      :attr:`shape_sequence` is a :class:`~kivy.properties.ListProperty`
      and defaults to::

          [
              "cookie12Sided",
              "pentagon",
              "pill",
              "verySunny",
              "cookie4Sided",
              "oval",
              "flower",
              "softBoom",
          ]


   .. py:attribute:: shape_size

      Size of the loading indicator.

      :attr:`shape_size` is a :class:`~kivy.properties.NumericProperty`
      and defaults to `dp(48)`.


   .. py:attribute:: duration

      Duration of one morph-and-rotate cycle in seconds.

      This value controls the overall speed of the loading indicator.

      :attr:`duration` is a :class:`~kivy.properties.NumericProperty`
      and defaults to `0.65`.


   .. py:attribute:: active_indicator_color

      Color of the active (foreground) loading shape.

      :attr:`active_indicator_color` is a :class:`~kivy.properties.ColorProperty`
      and defaults to `None`.


   .. py:attribute:: container_color

      Background container color of the indicator.

      :attr:`container_color` is a :class:`~kivy.properties.ColorProperty`
      and defaults to `None`.


   .. py:attribute:: shape_index

      Current index in the :attr:`shape_sequence`.

      :attr:`shape_index` is a :class:`~kivy.properties.NumericProperty`
      and defaults to `0`.


   .. py:method:: start(*args)

      Start the loading animation.

      Initiates the shape morphing and rotation cycle.
      The indicator continuously transitions between the shapes defined in
      :attr:`shape_sequence` while rotating at regular intervals.

      If already active, the animation sequence is reset.


   .. py:method:: stop(*args)

      Stop the loading animation.


   .. py:method:: get_shape_names()

      Return all available material shape names.