Circular Progress

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

Installation

$ cbui-cli install 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" />

Glass Effect

Apply a frosted glass effect to the background area of the progress circle using isGlass. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). The track color automatically adapts for visibility on the blurred background. Label and value label colors default to the theme's foreground. For dark glass tints or if the default foreground color lacks contrast, you may need to manually set labelColor, valueLabelColor, or use the styles prop to ensure readability.

MyComponent.tsx

<View style={{ flexDirection: 'row', alignItems: 'center', gap: 24, padding: 16, backgroundColor: 'darkslategray' }}>
  <CircularProgress
    value={70}
    isGlass
    glassIntensity={80}
    glassTint="light"
    label="Light Glass"
    showValueLabel
  />
  <CircularProgress
    value={50}
    isGlass
    glassIntensity={50}
    glassTint="dark"
    label="Dark Glass"
    showValueLabel
    styles={{ label: { color: 'white' }, valueLabel: { color: 'white' } }} // Example: manual text color for dark glass
  />
  <CircularProgress isIndeterminate isGlass glassIntensity={60} label="Indeterminate" styles={{ label: { color: 'lightgray' } }}/>
</View>

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-derived color and the default track color used with `isGlass`.
`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.
`isGlass`	`boolean`	`false`	Apply glassmorphism effect to the background area where the track is drawn.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the glass effect. If 'default', it's derived from the current theme mode.
`glassIntensity`	`number`	`30`	Intensity (0-100) for the glass effect.

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.
When isGlass is true, a BlurView is rendered as the background. The style prop (or styles.base) applies to the container that holds this BlurView, SVG, and labels. The trackColor prop can still override the default glass track color.

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