Getting started

Requirements

Platform	Minimum
Android	minSdk 24
iOS, macOS	iOS 15, macOS 12, Swift 5.9
Windows	Windows 10 version 1809 (build 17763), Windows App SDK 1.8, .NET 8
Web	Any browser with <canvas> and custom elements

Install

npm

npm install @loader-kit/web

yarn

yarn add @loader-kit/web

pnpm

pnpm add @loader-kit/web

Android (Gradle)

dependencies {
    implementation("io.github.maitrungduc1410:loaderkit-core:<version>")
    // Jetpack Compose (includes loaderkit-core):
    implementation("io.github.maitrungduc1410:loaderkit-compose:<version>")
}

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/maitrungduc1410/loader-kit.git", from: "<version>"),
],
targets: [
    .target(name: "App", dependencies: [.product(name: "LoaderKit", package: "loader-kit")]),
]

CocoaPods

pod 'LoaderKit', :git => 'https://github.com/maitrungduc1410/loader-kit.git', :tag => '<version>'

NuGet

dotnet add package LoaderKit.WinUI

• Replace <version> with the latest release from the GitHub releases. Tags have no v prefix.
• Android: both artifacts are on Maven Central, so mavenCentral() must be in your repositories.
• Apple: in Xcode you can also use File > Add Package Dependencies and enter the repository URL. The pod is not on the CocoaPods trunk: point the Podfile at the repository and a release tag.
• Windows: LoaderKit.WinUI brings LoaderKit.Core with it.
• React Native: see React Native.

Your first indicator

Built-in or progress?

• No percentage, ever (waiting for a request, pull to refresh): use a built-in indicator, as below. There are 50 styles to pick from.
• The task has progress, even if it is unknown at first (a download, an upload, processing a file): use a progress indicator. Start it indeterminate with value null (nil in Swift), then set a value once you know it. It is the same component, so nothing else changes.

Each snippet shows BallSpinFadeLoader in purple, 1.5 times faster than normal.

React

import { LoaderKit } from '@loader-kit/web/react';

<LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" speed={1.5} />

Vue

<script setup lang="ts">
import { LoaderKit } from '@loader-kit/web/vue';
</script>

<template>
  <LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" :speed="1.5" />
</template>

Svelte

<script lang="ts">
  import { LoaderKit } from '@loader-kit/web/svelte';
</script>

<LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" speed={1.5} />

HTML

<script type="module">
  import '@loader-kit/web/element';
</script>

<loader-kit indicator="BallSpinFadeLoader" color="#7c3aed" speed="1.5"></loader-kit>

TypeScript

import { LoaderKitView } from '@loader-kit/web';

const view = new LoaderKitView(document.querySelector('#loader')!, {
  indicator: 'BallSpinFadeLoader',
  color: '#7c3aed',
  speed: 1.5,
});

Android XML

<io.github.maitrungduc1410.loaderkit.LoaderKitView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:indicator="BallSpinFadeLoader"
    app:indicatorColor="#7C3AED"
    app:speed="1.5" />

Kotlin (View)

import io.github.maitrungduc1410.loaderkit.LoaderKitView

val loader = LoaderKitView(context).apply {
    indicator = "BallSpinFadeLoader"
    color = Color.parseColor("#7C3AED")
    speed = 1.5
}
container.addView(loader)

Compose

import io.github.maitrungduc1410.loaderkit.compose.LoaderKitIndicator

LoaderKitIndicator(
    indicator = "BallSpinFadeLoader",
    modifier = Modifier.size(48.dp),
    color = Color(0xFF7C3AED),
    speed = 1.5,
)

Swift (UIKit)

import LoaderKit

let loader = LoaderKitView(indicator: "BallSpinFadeLoader")
loader.color = .systemPurple
loader.speed = 1.5
view.addSubview(loader)

SwiftUI

import LoaderKit
import SwiftUI

struct LoadingView: View {
    var body: some View {
        LoaderKitIndicator("BallSpinFadeLoader")
            .color(.purple)
            .speed(1.5)
            .frame(width: 48, height: 48)
    }
}

XAML

<Page xmlns:lk="using:LoaderKit.WinUI">
    <lk:LoaderKitIndicator Indicator="BallSpinFadeLoader" Color="#7C3AED" Speed="1.5" />
</Page>

C#

using LoaderKit.WinUI;
using Microsoft.UI;

var indicator = new LoaderKitIndicator
{
    Indicator = "BallSpinFadeLoader",
    Color = ColorHelper.FromArgb(255, 0x7C, 0x3A, 0xED),
    Speed = 1.5,
};

Result:

Default size

Every view is 40 by 40 (dp, points, effective pixels or CSS pixels) unless you size it. The indicator is drawn in the largest square that fits, centered in the view. So a wide view draws a centered indicator, not a stretched one.

Stopping the indicator

Indicators start animating as soon as they are shown. When the work is done, stop them. By default a stopped indicator draws nothing.

TypeScript

view.stop();      // or view.animating = false
view.destroy();   // when you remove it for good

Kotlin (View)

loader.stop()     // or loader.isAnimating = false

Compose

LoaderKitIndicator("BallSpinFadeLoader", animating = isLoading)

Swift (UIKit)

loader.stopAnimating()   // or loader.isAnimating = false

SwiftUI

LoaderKitIndicator("BallSpinFadeLoader").animating(isLoading)

C#

indicator.IsAnimating = false;

See Playback for speed, freezing a frame and reduced motion.

Next steps

• Built-in indicators: pick an indicator.
• Progress indicators: show how much of a task is done.
• Customizing: params, colors and size.
• Platform pages: Web, Android, iOS and macOS, Windows.