Circular Progress

The CircularProgress component displays progress indication in a circular format, suitable for showing loading states or completion percentages.

Installation

$ cbui-cli install @crossbuildui/circular-progress

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

MyComponent.tsx

import { CircularProgress } from '@/crossbuildui/circular-progress';

CircularProgress Component

Basic Usage

Provide a value between minValue (default 0) and maxValue (default 100).

MyComponent.tsx

<CircularProgress value={50} />

With Label

Display a descriptive label inside or below the progress circle.

MyComponent.tsx

<CircularProgress value={75} label="Loading..." />

Sizes

The component comes in three predefined sizes: sm, md (default), and lg. You can also provide a number for a custom diameter.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 24 }}>
  <CircularProgress size="sm" value={30} showValueLabel />
  <CircularProgress size="md" value={60} showValueLabel />
  <CircularProgress size="lg" value={90} showValueLabel />
  <CircularProgress size={80} value={70} showValueLabel label="Custom Size (80)" />
</View>

Colors

Set the base thematic color using the color prop. Supported values include primary (default), secondary, success, warning, danger, and default. This base color influences the indicator and track colors by default.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 16 }}>
  <CircularProgress value={25} color="primary" showValueLabel />
  <CircularProgress value={50} color="secondary" showValueLabel />
  <CircularProgress value={75} color="success" showValueLabel />
  <CircularProgress value={60} color="warning" showValueLabel />
  <CircularProgress value={40} color="danger" showValueLabel />
  <CircularProgress value={80} color="default" showValueLabel />
</View>

Custom Individual Colors

For more granular control, you can use specific color props:indicatorColor, trackColor, labelColor, and valueLabelColor. These props override any colors derived from the theme or the base color prop.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 16 }}>
  <CircularProgress
    value={65}
    label="Custom Colors"
    indicatorColor="purple"
    trackColor="lightpink"
    labelColor="darkmagenta"
    valueLabelColor="indigo"
    showValueLabel
  />
</View>

Value Label

Use showValueLabel to display the current value, formatted by default or using formatOptions. You can also provide a custom valueLabel.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 24 }}>
  <CircularProgress value={66} showValueLabel />
  <CircularProgress value={33} valueLabel="1/3 Done" showValueLabel />
  <CircularProgress value={88} showValueLabel formatOptions={{ style: 'percent', minimumFractionDigits: 1 }} />
</View>

Indeterminate

Set isIndeterminate to true for an animated loading state when the progress value is unknown. This overrides the value prop.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 24 }}>
  <CircularProgress isIndeterminate label="Processing..." />
  <CircularProgress isIndeterminate color="success" size="sm" />
</View>

Custom Stroke Width

Customize the thickness of the progress circle using the strokeWidth prop.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 24 }}>
  <CircularProgress value={50} strokeWidth={2} size="md" showValueLabel />
  <CircularProgress value={75} strokeWidth={8} size="lg" showValueLabel label="Thick Stroke" />
</View>

Disabled State

Set isDisabled to true to visually mute the progress indicator.

MyComponent.tsx

<CircularProgress value={70} isDisabled label="Disabled" showValueLabel />

Disable Animation

Set disableAnimation to true to prevent animations on value changes or for indeterminate state.

MyComponent.tsx

<CircularProgress value={60} disableAnimation showValueLabel label="No Animation" />

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`label`	`ReactNode`	-	Content for the main label.
`size`	`'sm' \| 'md' \| 'lg' \| number`	`'md'`	Size of the progress indicator. Number sets custom diameter.
`value`	`number`	-	Current progress value (0-100 by default). Overridden by `isIndeterminate`.
`valueLabel`	`ReactNode`	-	Custom content for the value label.
`minValue`	`number`	`0`	Minimum progress value.
`maxValue`	`number`	`100`	Maximum progress value.
`formatOptions`	`Intl.NumberFormatOptions`	-	Formatting options for the displayed value.
`showValueLabel`	`boolean`	true if `value` is provided & not `isIndeterminate`, else false	Whether to display the value label.
`strokeWidth`	`number`	Varies by size (e.g., 4 for 'md'); dynamic for numeric size	Width of the progress stroke.
`color`	`CircularProgressColor`	`'primary'`	Thematic color of the indicator.
`indicatorColor`	`string`	-	Custom color for the progress indicator circle. Overrides theme/color prop.
`trackColor`	`string`	-	Custom color for the track circle. Overrides theme/color prop.
`labelColor`	`string`	-	Custom color for the label text. Overrides theme.
`valueLabelColor`	`string`	-	Custom color for the value label text. Overrides theme or indicator color.
`isDisabled`	`boolean`	`false`	If true, visually mutes the component.
`disableAnimation`	`boolean`	`false`	If true, disables all animations.
`isIndeterminate`	`boolean`	`false`	If true, shows an indeterminate loading animation.
`styles`	`CircularProgressSlotsStyles`	-	Custom styles for internal slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the main wrapper View.

Styling

Customize the CircularProgress appearance using several methods:

Direct color props: indicatorColor, trackColor, labelColor, valueLabelColor for specific parts.
The style prop for the main container.
The styles prop for more granular control over internal elements (slots). Styles applied here can override the direct color props.

The styles prop accepts an object where keys correspond to different parts of the component:

base: The main wrapper View.
svg: The View container for the SVG element.
track: The background circle (Circle component from react-native-svg). You can pass SVG props like stroke, strokeOpacity etc.
indicator: The progress indicator circle (AnimatedCircle). You can pass SVG props.
label: The label Text component.
valueLabel: The value label Text component.

Styling SVG Elements

When styling track and indicator slots, you are passing props directly to SVG Circle components. For example, to change the track color via the styles prop, you would use { track: { stroke: 'yourColor' } }. This is different from typical ViewStyle or TextStyle props.

MyComponent.tsx

<CircularProgress
  value={80}
  label="Custom Style"
  showValueLabel
  color="primary"
  size="lg"
  strokeWidth={6}
  style={{ transform: [{ scale: 1.1 }] }} // Styles the outermost 'base' container
  styles={{
    base: { opacity: 0.9 },
    svg: { transform: [{ rotate: '10deg' }] }, // Example: slightly rotate the SVG
    track: { stroke: 'lightgray', strokeOpacity: 0.5 },
    indicator: { strokeLinecap: 'butt' }, // Change from default 'round'
    label: { color: 'blue', fontSize: 16, fontWeight: 'bold' },
    valueLabel: { color: 'darkblue', fontStyle: 'italic' }
  }}
/>

Accessibility

The CircularProgress component includes accessibility features:

The root View has accessibilityRole="progressbar".
Accessibility properties accessibilityValue.min, accessibilityValue.max, and accessibilityValue.now are set based on the minValue, maxValue, and value props respectively.
If a label is provided, it helps describe the progress indicator. Ensure the label is meaningful.
When isIndeterminate is true, the component signifies an ongoing process without a specific completion percentage. Screen readers should announce this appropriately.

Alert Modal

Circular Progress

Installation

Import

CircularProgress Component

Basic Usage

With Label

Sizes

Colors

Custom Individual Colors

Value Label

Indeterminate

Custom Stroke Width

Disabled State

Disable Animation

Props Overview

Styling

Accessibility

With Label & Value

Format Options

Custom Style