Progress

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

Installation

$ cbui-cli install @crossbuildui/progress

Import

MyComponent.tsx
1import { Progress } from '@/crossbuildui/progress'; 2import type { ProgressColor, ProgressRadius, ProgressSize } from '@/crossbuildui/progress'; // Optional: for type safety 3import { View, Text } from 'react-native'; // For layout and labels

Progress Component

Basic Usage

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

MyComponent.tsx
1<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
1<View style={{ gap: 16 }}> 2 <Progress value={75} label="Task Completion" /> 3 <Progress value={30} valueLabel="30%" /> 4 <Progress value={60} label="Upload Progress" valueLabel="60/100MB" /> 5</View>

Sizes

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

MyComponent.tsx
1<View style={{ gap: 16, width: '80%' }}> 2 <Progress size="sm" value={30} label="Small (sm)" valueLabel="30%" /> 3 <Progress size="md" value={60} label="Medium (md)" valueLabel="60%" /> 4 <Progress size="lg" value={90} label="Large (lg)" valueLabel="90%" /> 5</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
1<View style={{ gap: 16, width: '80%' }}> 2 <Progress value={25} color="primary" label="Primary" /> 3 <Progress value={40} color="secondary" label="Secondary" /> 4 <Progress value={55} color="success" label="Success" /> 5 <Progress value={70} color="warning" label="Warning" /> 6 <Progress value={85} color="danger" label="Danger" /> 7 <Progress value={50} color="default" label="Default" /> 8</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
1<View style={{ gap: 16, width: '80%' }}> 2 <Progress value={50} radius="none" label="No Radius (none)" /> 3 <Progress value={50} radius="sm" label="Small Radius (sm)" /> 4 <Progress value={50} radius="md" label="Medium Radius (md)" /> 5 <Progress value={50} radius="lg" label="Large Radius (lg)" /> 6 <Progress value={50} radius="full" label="Full Radius (pill)" /> 7</View>

Striped

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

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

Animation Control

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

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

Props Overview

PROPTYPEDEFAULTDESCRIPTION
labelReactNode-Main label for the progress bar.
sizeProgressSize'md'Size (height) of the progress bar.
colorProgressColor'primary'Thematic color of the indicator.
radiusProgressRadius'md'Border radius of track and indicator.
valuenumber-Current progress value.
valueLabelReactNode-Label for the current value (e.g., "50%").
minValuenumber0Minimum progress value.
maxValuenumber100Maximum progress value.
isStripedbooleanfalseIf true, indicator has a striped appearance.
disableAnimationbooleanfalseIf true, disables animation on value change.
stylesProgressSlotsStyles-Custom styles for internal slots.
styleStyleProp<ViewStyle>-Style for the outermost container.
animationDurationnumber300Duration of animation in milliseconds.

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.
MyComponent.tsx
1<Progress 2 value={75} 3 label="Custom Styled Progress" 4 valueLabel="75 Points" 5 color="warning" // Base color for indicator 6 size="lg" 7 radius="sm" 8 style={{ opacity: 0.9, marginVertical: 10 }} // Styles the outermost 'base' container 9 styles={{ 10 base: { borderWidth: 1, borderColor: 'gray' }, 11 labelWrapper: { marginBottom: 8 }, 12 label: { color: 'purple', fontSize: 16, fontWeight: 'bold' }, 13 valueLabel: { color: 'darkorange', fontStyle: 'italic' }, 14 track: { backgroundColor: '#e0e0e0', height: 15 }, // Custom track 15 indicator: { borderWidth: 2, borderColor: 'black' } // Custom indicator styles (backgroundColor will be from 'color' prop) 16 }} 17/>

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