# Loading

Kickstand UI's loading component is designed to communicate unseen progress to the user. There are two ways to display loading indicators - inline or in an overlay.

# Types

<ks-loading icon="ring_spinner"></ks-loading>
<ks-loading icon="circle_spinner"></ks-loading>
<ks-loading icon="ellipsis_pulse"></ks-loading>
<ks-loading icon="ellipsis_typing"></ks-loading>

# Messaging


<ks-loading icon="ring_spinner" message="Spinner Loading..." show-message />
<ks-loading icon="ellipsis_typing" message="Ellipsis Loading..." show-message />

# Loading Overlay

The loading overlay combine the <ks-loading> element and the <ks-overlay> components to provide a flexible and dynamic loading component.

Show Loading
<ks-loading-overlay icon="circle_spinner" />

# Theme

You can choose the theme color of the overlay background using the theme property. the options are light and dark.

# Sizes

Changing the size of the <ks-loading /> is as easy as changing the font size on the element. You can quickly do that without aline of CSS using one of the text utility classes (<ks-loading class="text-lg" />).

Changing the size of the <ks-loading-overlay /> can be done using the custom size attribute. Sizes include xxs-xxl.

Show XL Loading
<ks-loading-overlay size="xxl" />

# Positioning

By default the overlay will take up the entire viewport. If you are only loading a portion of the page, you can isolate the loading overlay to that specific area by placing the component within the container you are loading and adding the absolute attribute to the component.

Note

The parent container must have the CSS rule position: relative; set. Feel free to take advantage of our position-relative utility class to make it easy.

Show Absolute Overlay
<div class="position-relative" style="width:300px;height:150px;">
    <ks-button id="absolute_button">Show Absolute Overlay</ks-button>
    <ks-loading-overlay id="absolute_overlay" size="xxl" absolute />
    <script>
        let absoluteButton = document.getElementById('absolute_button');
        let absoluteOverlay = document.getElementById('absolute_overlay');
        absoluteButton.addEventListener('click', () => {
            absoluteOverlay.show();
            setTimeout(function() {
                absoluteOverlay.hide();
            }, 3000);
        });
    </script>
</div>

# Showing and Hiding

Showing and hiding the loading overlay is as simple as using JavaScript to select the element and call the show() or hide() methods. Here is a simple example that will show the overlay when the button is clicked and hide it after 3 seconds.

Show Overlay
<ks-button id="test_button">Show Overlay</ks-button>
<ks-loading-overlay id="test_overlay" size="xxl" />
<script>
    let testOverlay = document.getElementById('test_overlay');
    let testButton = document.getElementById('test_button');

    // add click event listener to button
    testButton.addEventListener('click', () => {
        // show loading overlay
        testOverlay.show();

        // hide after 3 seconds
        setTimeout(function() {
            testOverlay.hide();
        }, 3000);
    });
</script>

# Button Attributes

If you are using the <ks-button> element you can take advantage of the shows and hides properties to open and close any of the components built using the overlay component.

Show Overlay
Hide Overlay
<div class="position-relative" style="width:300px;height:150px;">
    <ks-button shows="show_overlay">Show Overlay</ks-button>
    <ks-loading-overlay id="show_overlay" size="lg" absolute />
</div>
<ks-button hides="show_overlay">Hide Overlay</ks-button>

# Accessibility

The loading icon itself is hidden to screen readers using aria-hidden="true" attribute, but the message is announced when the icons is displayed using the role="alert" and aria-live="polite" attributes.

The loading overlay has the same features, but is also built with the <ks-overlay> component and takes advantage of its accessibility features. The main feature is that it uses the role="dialog" attribute to notify screen readers that a dialog is open when the loading overlay is displayed.

# Properties

# Loading

Property Attribute Description Type Default
message message text to display with loading icon string 'Loading...'
showMessage show-message toggle message visibility boolean false
type type type of icon "ellipsis" or "spinner" 'spinner'

# Loading Overlay

Property Attribute Description Type Default
absolute absolute controls where overlay displays boolean false
theme theme customizes the the overlay theme light or dark light
message message text to display with loading icon string 'Loading...'
showMessage show-message toggle message visibility boolean false
size size size of icon "lg", "md", "sm", "xl", "xs", "xxl", or "xxs" 'sm'
type type type of icon "ellipsis" or "spinner" 'spinner'

# Events

Event Description Type
hidden emitted when overlay is hidden CustomEvent<any>
shown emitted when overlay is shown CustomEvent<any>
<ks-loading-overlay id="my_overlay">
    ...
</ks-loading-overlay>

<script>
    let myOverlay = document.getElementById('my_overlay');

    myOverlay.addEventListener('hidden', () => {
        // do something...
    });
</script>

# Methods

# hide() => Promise<void>

# Returns

Type: Promise<void>

# show() => Promise<void>

# Returns

Type: Promise<void>