Progress

The Progress component displays a linear progress bar, ideal for showing task completion, loading states, or any quantifiable progression.

Installation

$ cbui-cli install 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 { Progress } from '@/crossbuildui/progress';
import type { ProgressColor, ProgressRadius, ProgressSize } from '@/crossbuildui/progress'; // Optional: for type safety
import { View, Text } from 'react-native'; // For layout and labels

The isGlass feature for the progress track uses expo-blur. Ensure this library is installed and linked if you plan to use this feature.

Progress Component

Basic Usage

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

MyComponent.tsx

<Progress value={50} />

With Labels

Display a descriptive label and/or a valueLabel above the progress bar. The valueLabel should be a string or ReactNode representing the current value (e.g., "50%", "Step 2 of 5").

MyComponent.tsx

<View style={{ gap: 16 }}>
  <Progress value={75} label="Task Completion" />
  <Progress value={30} valueLabel="30%" />
  <Progress value={60} label="Upload Progress" valueLabel="60/100MB" />
</View>

Sizes

The component comes in three predefined sizes affecting its height: sm, md (default), and lg.

MyComponent.tsx

<View style={{ gap: 16, width: '80%' }}>
  <Progress size="sm" value={30} label="Small (sm)" valueLabel="30%" />
  <Progress size="md" value={60} label="Medium (md)" valueLabel="60%" />
  <Progress size="lg" value={90} label="Large (lg)" valueLabel="90%" />
</View>

Colors

Set the thematic color of the indicator using the color prop. Supported colors: primary (default), secondary, success, warning, danger, and default.

MyComponent.tsx

<View style={{ gap: 16, width: '80%' }}>
  <Progress value={25} color="primary" label="Primary" />
  <Progress value={40} color="secondary" label="Secondary" />
  <Progress value={55} color="success" label="Success" />
  <Progress value={70} color="warning" label="Warning" />
  <Progress value={85} color="danger" label="Danger" />
  <Progress value={50} color="default" label="Default" />
</View>

Radius

Adjust the border radius of the track and indicator using the radius prop. Options: none, sm, md (default), lg, full (pill shape).

MyComponent.tsx

<View style={{ gap: 16, width: '80%' }}>
  <Progress value={50} radius="none" label="No Radius (none)" />
  <Progress value={50} radius="sm" label="Small Radius (sm)" />
  <Progress value={50} radius="md" label="Medium Radius (md)" />
  <Progress value={50} radius="lg" label="Large Radius (lg)" />
  <Progress value={50} radius="full" label="Full Radius (pill)" />
</View>

Striped

Set isStriped to true for a striped visual effect on the indicator. This uses expo-linear-gradient.

Dependency

The isStriped feature requires expo-linear-gradient to be installed in your project.
npm install expo-linear-gradient or yarn add expo-linear-gradient

MyComponent.tsx

<View style={{ gap: 16, width: '80%' }}>
  <Progress value={70} isStriped label="Striped Primary" />
  <Progress value={60} color="success" isStriped label="Striped Success" />
</View>

Animation Control

Control the progress animation with disableAnimation (boolean) and animationDuration (number, in milliseconds).

MyComponent.tsx

<View style={{ gap: 16, width: '80%' }}>
  <Progress value={80} disableAnimation label="Animation Disabled" />
  <Progress value={65} animationDuration={1000} label="Slow Animation (1s)" />
  <Progress value={50} animationDuration={100} label="Fast Animation (0.1s)" />
</View>

Glass Track Effect

Apply a frosted glass effect to the progress bar's track (background) using isGlass. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). When isGlass is true, the track's direct background color becomes transparent, and a BlurView provides the visual effect. Label and value label colors default to the theme's foreground color for better contrast on the blurred background. For dark glass tints, you might need to manually set label colors via the styles prop. The indicator renders on top of this glass track.

MyComponent.tsx

<View style={{ gap: 16, width: '80%', padding: 10, backgroundColor: 'rgba(0,0,0,0.1)' /* Example background */ }}>
  <Progress
    value={70}
    isGlass
    glassIntensity={80}
    glassTint="light"
    label="Light Glass Track"
    valueLabel="70%"
  />
  <Progress
    value={50}
    isGlass
    glassIntensity={50}
    glassTint="dark"
    label="Dark Glass Track"
    valueLabel="50%"
    styles={{ label: { color: 'white' }, valueLabel: { color: 'white' } }} // Example: manual text color for dark glass
  />
</View>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`label`	`ReactNode`	-	Main label for the progress bar.
`size`	`ProgressSize`	`'md'`	Size (height) of the progress bar.
`color`	`ProgressColor`	`'primary'`	Thematic color of the indicator.
`radius`	`ProgressRadius`	`'md'`	Border radius of track and indicator.
`value`	`number`	-	Current progress value.
`valueLabel`	`ReactNode`	-	Label for the current value (e.g., "50%").
`minValue`	`number`	`0`	Minimum progress value.
`maxValue`	`number`	`100`	Maximum progress value.
`isStriped`	`boolean`	`false`	If true, indicator has a striped appearance.
`disableAnimation`	`boolean`	`false`	If true, disables animation on value change.
`styles`	`ProgressSlotsStyles`	-	Custom styles for internal slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the outermost container.
`animationDuration`	`number`	`300`	Duration of animation in milliseconds.
`isGlass`	`boolean`	`false`	Apply glassmorphism effect to the track background.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the glass effect on the track.
`glassIntensity`	`number`	`30`	Intensity (0-100) for the glass effect on the track.

Styling

Customize the Progress component's appearance using the style prop for the main container or the styles prop for more granular control over internal elements (slots).

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

base: The main wrapper View.
labelWrapper: The View containing the label and valueLabel.
label: The label Text component.
valueLabel: The value label Text component.
track: The background View of the progress bar.
indicator: The foreground Animated.View showing the progress.
When isGlass is true, a BlurView is rendered as the background for the track. The track style's backgroundColor will be set to transparent.

Indicator Styling

The color prop primarily determines the indicator's background color (or base colors for isStriped). If you provide styles.indicator.backgroundColor for a non-striped progress, it will override the color derived from the color prop. For a striped progress, styles.indicator applies to the container of the LinearGradient, not the gradient colors themselves.

MyComponent.tsx

<Progress
  value={75}
  label="Custom Styled Progress"
  valueLabel="75 Points"
  color="warning" // Base color for indicator
  size="lg"
  radius="sm"
  style={{ opacity: 0.9, marginVertical: 10 }} // Styles the outermost 'base' container
  styles={{
    base: { borderWidth: 1, borderColor: 'gray' },
    labelWrapper: { marginBottom: 8 },
    label: { color: 'purple', fontSize: 16, fontWeight: 'bold' },
    valueLabel: { color: 'darkorange', fontStyle: 'italic' },
    track: { backgroundColor: '#e0e0e0', height: 15 }, // Custom track
    indicator: { borderWidth: 2, borderColor: 'black' } // Custom indicator styles (backgroundColor will be from 'color' prop)
  }}
/>

Accessibility

The Progress component includes accessibility features:

The root View has accessibilityRole="progressbar".
Accessibility properties accessibilityValue.min, accessibilityValue.max, and accessibilityValue.now are automatically set based on the minValue, maxValue, and value props respectively.
If a label is provided, it serves as the primary accessibility label for the progress bar. Ensure it is descriptive.
The valueLabel can provide additional context to screen reader users if it's a string.

Modal Skeleton