or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

@chakra-ui/progress

@chakra-ui/progress provides React progress components for the Chakra UI design system, including both linear and circular progress indicators. It offers comprehensive progress bar functionality with features like customizable colors, sizes, striped patterns, animations, indeterminate states, and full accessibility support through proper ARIA attributes.

Package Information

  • Package Name: @chakra-ui/progress
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @chakra-ui/progress

Core Imports

import {
  Progress,
  ProgressLabel,
  CircularProgress,
  CircularProgressLabel,
  useProgressStyles,
  type ProgressProps,
  type ProgressLabelProps,
  type ProgressFilledTrackProps,
  type ProgressTrackProps,
  type CircularProgressProps,
  type CircularProgressLabelProps
} from "@chakra-ui/progress";

For CommonJS:

const {
  Progress,
  ProgressLabel,
  CircularProgress,
  CircularProgressLabel,
  useProgressStyles
} = require("@chakra-ui/progress");

Basic Usage

import { Progress, ProgressLabel, CircularProgress } from "@chakra-ui/progress";

// Linear progress
<Progress value={50} />

// Linear progress with label
<Progress value={60}>
  <ProgressLabel>60%</ProgressLabel>
</Progress>

// Circular progress
<CircularProgress value={75} />

// Indeterminate progress
<Progress isIndeterminate />

Architecture

@chakra-ui/progress is built around four main components:

  • Progress: Linear progress bar with theming, striping, and animation support
  • ProgressLabel: Text label component for displaying progress values inside linear progress bars
  • CircularProgress: Circular progress indicator with size, thickness, and color customization
  • CircularProgressLabel: Text label component for displaying values inside circular progress indicators
  • Context System: Uses React Context for style management and component composition

Capabilities

Linear Progress

Linear progress bars for indicating task completion with support for theming, striping, and animations.

interface ProgressProps extends HTMLChakraProps<"div"> {
  /** The value of the progress indicator. If undefined the progress bar will be in indeterminate state */
  value?: number;
  /** The minimum value of the progress @default 0 */
  min?: number;
  /** The maximum value of the progress @default 100 */  
  max?: number;
  /** If true, the progress bar will show stripe @default false */
  hasStripe?: boolean;
  /** If true, and hasStripe is true, the stripes will be animated @default false */
  isAnimated?: boolean;
  /** If true, the progress will be indeterminate and the value prop will be ignored @default false */
  isIndeterminate?: boolean;
  /** Color scheme for theming */
  colorScheme?: string;
  /** Size variant */
  size?: string;
}

const Progress: React.ForwardRefExoticComponent<ProgressProps & React.RefAttributes<HTMLDivElement>>;

Usage Examples:

import { Progress } from "@chakra-ui/progress";

// Basic progress
<Progress value={30} />

// Colored progress
<Progress colorScheme="green" value={40} />

// Striped progress
<Progress hasStripe value={50} />

// Animated striped progress
<Progress hasStripe isAnimated value={60} />

// Different sizes
<Progress size="sm" value={25} />
<Progress size="lg" value={75} />

// Indeterminate progress
<Progress isIndeterminate />

Linear Progress Label

Label component for displaying numeric progress values inside linear progress bars.

interface ProgressLabelProps extends HTMLChakraProps<"div"> {}

const ProgressLabel: React.FC<ProgressLabelProps>;

Usage Examples:

import { Progress, ProgressLabel } from "@chakra-ui/progress";

// Progress with percentage label
<Progress value={65}>
  <ProgressLabel>65%</ProgressLabel>
</Progress>

// Progress with custom label
<Progress value={8} max={10}>
  <ProgressLabel>8 of 10 tasks</ProgressLabel>
</Progress>

Circular Progress

Circular progress indicators with customizable size, thickness, colors, and animations.

interface CircularProgressProps extends Omit<HTMLChakraProps<"div">, "color"> {
  /** The size of the circular progress in CSS units @default "48px" */
  size?: string | number;
  /** Maximum value defining 100% progress made @default 100 */
  max?: number;
  /** Minimum value defining 'no progress' @default 0 */
  min?: number; 
  /** This defines the stroke width of the svg circle @default "10px" */
  thickness?: string | number;
  /** Current progress (must be between min/max) */
  value?: number;
  /** If true, the cap of the progress indicator will be rounded @default false */
  capIsRound?: boolean;
  /** The content of the circular progress bar. If passed, the content will be inside and centered in the progress bar */
  children?: React.ReactNode;
  /** The color name of the progress track. Use a color key in the theme object @default "#edebe9" */
  trackColor?: string;
  /** The color of the progress indicator. Use a color key in the theme object @default "#0078d4" */
  color?: string;
  /** The desired valueText to use in place of the value */
  valueText?: string;
  /** A function that returns the desired valueText to use in place of the value */
  getValueText?(value: number, percent: number): string;
  /** If true, the progress will be indeterminate and the value prop will be ignored @default false */
  isIndeterminate?: boolean;
}

const CircularProgress: React.ForwardRefExoticComponent<CircularProgressProps & React.RefAttributes<HTMLDivElement>>;

Usage Examples:

import { CircularProgress } from "@chakra-ui/progress";

// Basic circular progress
<CircularProgress value={40} />

// Large circular progress with thick stroke
<CircularProgress size="120px" thickness="12px" value={60} />

// Colored circular progress
<CircularProgress color="green.400" value={80} />

// Circular progress with rounded caps
<CircularProgress capIsRound value={70} />

// Indeterminate circular progress
<CircularProgress isIndeterminate />

// Custom colors (defaults: color="#0078d4", trackColor="#edebe9")
<CircularProgress 
  value={50} 
  color="blue.400" 
  trackColor="gray.200" 
/>

Circular Progress Label

Label component for displaying text and values inside circular progress indicators.

interface CircularProgressLabelProps extends HTMLChakraProps<"div"> {}

const CircularProgressLabel: ChakraComponent<"div", CircularProgressLabelProps>;

Usage Examples:

import { CircularProgress, CircularProgressLabel } from "@chakra-ui/progress";

// Circular progress with percentage
<CircularProgress value={60}>
  <CircularProgressLabel>60%</CircularProgressLabel>
</CircularProgress>

// Circular progress with custom label
<CircularProgress value={7} max={10}>
  <CircularProgressLabel>7/10</CircularProgressLabel>
</CircularProgress>

Progress Styles Hook

Hook for accessing progress component styles from context, useful for building custom progress components.

// Import types from @chakra-ui/system
type SystemStyleObject = import("@chakra-ui/system").SystemStyleObject;
type HTMLChakraProps<T extends keyof JSX.IntrinsicElements> = import("@chakra-ui/system").HTMLChakraProps<T>;
type ChakraComponent<T, P> = import("@chakra-ui/system").ChakraComponent<T, P>;

function useProgressStyles(): Record<string, SystemStyleObject>;

Usage Example:

import { useProgressStyles } from "@chakra-ui/progress";

function CustomProgressComponent() {
  const styles = useProgressStyles();
  
  return (
    <div style={styles.track}>
      <div style={styles.filledTrack} />
    </div>
  );
}

Additional Type Interfaces

interface GetProgressPropsOptions {
  /** Current progress value */
  value?: number;
  /** Minimum value defining 'no progress' */
  min: number;
  /** Maximum value defining 100% progress */
  max: number;
  /** The desired valueText to use in place of the value */
  valueText?: string;
  /** A function that returns the desired valueText to use in place of the value */
  getValueText?(value: number, percent: number): string;
  /** If true, the progress will be indeterminate */
  isIndeterminate?: boolean;
  /** ARIA role for accessibility */
  role?: React.AriaRole;
}

interface ProgressFilledTrackProps extends HTMLChakraProps<"div">, GetProgressPropsOptions {}

interface ProgressTrackProps extends HTMLChakraProps<"div"> {}

Accessibility Features

All progress components include comprehensive accessibility support:

  • ARIA Attributes: aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext
  • Role Support: Default progressbar role, configurable to meter
  • Screen Reader Support: Proper labeling and value announcements
  • Indeterminate State: Proper handling for unknown progress states
  • Custom Value Text: Support for descriptive progress text via valueText or getValueText

Accessibility Example:

<Progress 
  value={75}
  aria-label="Upload progress"
  aria-valuetext="75% uploaded"
/>

<CircularProgress 
  value={50}
  getValueText={(value, percent) => `${value} items processed (${percent}%)`}
/>

Error Handling

Progress components handle edge cases gracefully:

  • Values outside min/max range are clamped
  • Invalid or undefined values default to 0 or indeterminate state
  • Missing context providers provide helpful error messages