This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

Progress indicators

Jetpack Compose progress indicator components for displaying operation status.

Android

Included in Expo Go

GitHub

npm

Changelog

Expo UI Progress Indicators match the official Jetpack Compose Progress Indicator API.

Indeterminate circular progress indicator with two determinate linear progress bars at 30% and 75%

Installation

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Linear progress

A horizontal bar that fills to indicate progress. Provide a progress value between 0 and 1 for determinate mode.

LinearExample.tsx

import {
  Host,
  LinearProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function LinearExample() {
  return (
    <Host matchContents>
      <LinearProgressIndicator progress={0.5} />
    </Host>
  );
}

Circular progress

A spinning circle whose stroke grows to indicate progress.

CircularExample.tsx

import {
  Host,
  CircularProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function CircularExample() {
  return (
    <Host matchContents>
      <CircularProgressIndicator progress={0.75} />
    </Host>
  );
}

Indeterminate

Omit the progress prop to animate continuously without indicating a specific completion level.

IndeterminateExample.tsx

import {
  CircularProgressIndicator,
  CircularWavyProgressIndicator,
  Column,
  Host,
  LinearProgressIndicator,
  LinearWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function IndeterminateExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 16 }}>
        <LinearProgressIndicator />
        <CircularProgressIndicator />
        <CircularWavyProgressIndicator />
        <LinearWavyProgressIndicator />
      </Column>
    </Host>
  );
}

Custom colors

Use color for the indicator and trackColor for the background track.

ColorsExample.tsx

import {
  Host,
  CircularProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function ColorsExample() {
  return (
    <Host matchContents>
      <CircularProgressIndicator
        progress={0.6}
        color="red"
        trackColor="#cccccc"
      />
    </Host>
  );
}

Wavy variants

LinearWavyProgressIndicator and CircularWavyProgressIndicator add an expressive wave animation from Material 3 Expressive.

WavyExample.tsx

import {
  Host,
  LinearWavyProgressIndicator,
  CircularWavyProgressIndicator,
  Column,
} from '@expo/ui/jetpack-compose';

export default function WavyExample() {
  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 16 }}>
        <LinearWavyProgressIndicator progress={0.6} />
        <CircularWavyProgressIndicator progress={0.6} />
      </Column>
    </Host>
  );
}

Wave configuration

Use amplitude to set the wave height, from 0 for a flat line to 1 for the full height. Use wavelength to set the length of a single wave in dp, and waveSpeed to set how fast the wave travels in dp per second. waveSpeed defaults to wavelength. Set waveSpeed={0} to render a static wave.

WaveConfigExample.tsx

import {
  Host,
  LinearWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

export default function WaveConfigExample() {
  return (
    <Host matchContents>
      <LinearWavyProgressIndicator
        progress={0.6}
        amplitude={0.4}
        wavelength={24}
        waveSpeed={18}
      />
    </Host>
  );
}

API

import {
  LinearProgressIndicator,
  CircularProgressIndicator,
  LinearWavyProgressIndicator,
  CircularWavyProgressIndicator,
} from '@expo/ui/jetpack-compose';

Components

`CircularProgressIndicator`

Android

Type: React.Element<ComponentType<CircularProgressIndicatorProps>>

A circular progress indicator that displays progress in a circular format.

Matches the Jetpack Compose CircularProgressIndicator.

Common props shared by all progress indicator variants.

CircularProgressIndicatorProps

`gapSize`

Android

Optional • Type: number

Gap size between the indicator and track in dp.

`strokeCap`

Android

Optional • Type: StrokeCap • Default: 'round'

Stroke cap style for the indicator ends.

`strokeWidth`

Android

Optional • Type: number

Width of the circular stroke in dp.

Inherited props

ProgressCommonConfig

`CircularWavyProgressIndicator`

Android

Type: React.Element<ComponentType<CircularWavyProgressIndicatorProps>>

A circular progress indicator with wavy animation style.

Matches the Jetpack Compose CircularWavyProgressIndicator.

Common props shared by all progress indicator variants.

CircularWavyProgressIndicatorProps

Inherited props

`LinearProgressIndicator`

Android

Type: React.Element<ComponentType<LinearProgressIndicatorProps>>

A linear progress indicator that displays progress in a horizontal bar.

Matches the Jetpack Compose LinearProgressIndicator.

Common props shared by all progress indicator variants.

LinearProgressIndicatorProps

`drawStopIndicator`

Android

Optional • Type: DrawStopIndicatorConfig

Configuration for the stop indicator dot at the end of the determinate progress track.

`gapSize`

Android

Optional • Type: number

Gap size between the indicator and track in dp.

`strokeCap`

Android

Optional • Type: StrokeCap • Default: 'round'

Stroke cap style for the indicator ends.

Inherited props

ProgressCommonConfig

`LinearWavyProgressIndicator`

Android

Type: React.Element<ComponentType<LinearWavyProgressIndicatorProps>>

A linear progress indicator with wavy animation style.

Matches the Jetpack Compose LinearWavyProgressIndicator.

Common props shared by all progress indicator variants.

LinearWavyProgressIndicatorProps

`stopSize`

Android

Optional • Type: number

Size of the stop indicator in dp at the end of the determinate progress track.

Inherited props

Types

`DrawStopIndicatorConfig`

Android

Configuration for the stop indicator dot at the end of the determinate linear progress track. When provided, draws a stop indicator with the given options. Omit to use the Compose default.

Property	Type	Description
color(optional)	`ColorValue`	Color of the stop indicator. Defaults to the indicator's color.
stopSize(optional)	`number`	Size of the stop indicator in dp. Defaults to the Material 3 default.
strokeCap(optional)	`StrokeCap`	Stroke cap style for the stop indicator. Defaults to the indicator's strokeCap.

`ProgressCommonConfig`

Android

Common props shared by all progress indicator variants.

Property	Type	Description
color(optional)	`ColorValue`	Progress indicator color.
modifiers(optional)	`ModifierConfig[]`	Modifiers for the component.
progress(optional)	`number \| null`	The current progress value between `0` and `1`. Omit for indeterminate.
trackColor(optional)	`ColorValue`	Track (background) color.

`StrokeCap`

Android

Literal type: string

Stroke cap style for progress indicators.

Acceptable values are: 'round' | 'butt' | 'square'

`WavyProgressCommonConfig`

Android

Wave configuration shared by the wavy progress indicator variants.

Property	Type	Description
amplitude(optional)	`number`	Height of the wave, where `0` draws a flat line and `1` draws the full wave height. When set, the amplitude stays the same across the whole track. When omitted, a determinate indicator uses the Material 3 default, which flattens the wave as progress approaches `0` and `1`. An indeterminate indicator defaults to the full wave height.
wavelength(optional)	`number`	Length of a single wave in dp. `CircularWavyProgressIndicator` rounds this to fit a whole number of waves around the ring, so the wave it draws can be slightly shorter or longer.
waveSpeed(optional)	`number`	Speed of the wave in dp per second. Defaults to `wavelength`, which advances the wave by one wavelength per second. Set it to `0` to stop the wave from moving.