Overview
The CircularProgressBar component displays progress in a circular format, with options to show percentage text or custom icons in the center. It’s ideal for compact progress displays, dashboard widgets, and status indicators.
Basic Usage
import { CircularProgressBar } from '@ui-kitten/components';
const BasicCircularProgress = () => (
<CircularProgressBar progress={0.65} />
);
The current progress value, ranging from 0 to 1. For example, 0.65 represents 65% completion.
Whether the progress bar animates when the progress value changes. Set to false for instant updates.
Function component to render a custom icon in the center of the circular progress bar instead of the percentage text. Expected to return an Icon component.
status
EvaStatus
default:"primary"
Determines the color of the progress indicator. Available values:
basicprimarysuccessinfowarningdangercontrol - Use when displaying on high-contrast backgrounds
Controls the size of the circular progress bar. Available values:
tinysmallmediumlargegiant
Custom style object for the percentage text in the center.
Custom style object for the icon rendered in the center (when using renderIcon).
animationConfig
CircularProgressBarAnimationConfig
Configuration object for customizing the animation behavior. Can include properties like duration and easing function.
Custom style object to override default styling.
Examples
Different Sizes
import { CircularProgressBar, Layout } from '@ui-kitten/components';
const CircularProgressSizes = () => (
<Layout style={{ flexDirection: 'row', gap: 16, alignItems: 'center' }}>
<CircularProgressBar progress={0.75} size='tiny' />
<CircularProgressBar progress={0.75} size='small' />
<CircularProgressBar progress={0.75} size='medium' />
<CircularProgressBar progress={0.75} size='large' />
<CircularProgressBar progress={0.75} size='giant' />
</Layout>
);
Different Statuses
import { CircularProgressBar, Layout } from '@ui-kitten/components';
const CircularProgressStatuses = () => (
<Layout style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap' }}>
<CircularProgressBar progress={0.8} status='primary' />
<CircularProgressBar progress={0.8} status='success' />
<CircularProgressBar progress={0.8} status='info' />
<CircularProgressBar progress={0.8} status='warning' />
<CircularProgressBar progress={0.8} status='danger' />
</Layout>
);
With Custom Icon
import { CircularProgressBar, Icon } from '@ui-kitten/components';
const CheckIcon = (props) => (
<Icon {...props} name='checkmark-outline' />
);
const ErrorIcon = (props) => (
<Icon {...props} name='close-outline' />
);
const ProgressWithIcons = () => (
<Layout style={{ flexDirection: 'row', gap: 16 }}>
<CircularProgressBar
progress={1}
status='success'
renderIcon={CheckIcon}
/>
<CircularProgressBar
progress={0.3}
status='danger'
renderIcon={ErrorIcon}
/>
</Layout>
);
Task Completion Tracker
import React, { useState } from 'react';
import { CircularProgressBar, Layout, Text, CheckBox } from '@ui-kitten/components';
const TaskCompletionTracker = () => {
const [tasks, setTasks] = useState([
{ id: 1, title: 'Design mockups', completed: true },
{ id: 2, title: 'Write documentation', completed: true },
{ id: 3, title: 'Code review', completed: false },
{ id: 4, title: 'Deploy to production', completed: false },
]);
const completedCount = tasks.filter(t => t.completed).length;
const progress = completedCount / tasks.length;
const toggleTask = (id) => {
setTasks(tasks.map(task =>
task.id === id ? { ...task, completed: !task.completed } : task
));
};
const getStatus = () => {
if (progress === 1) return 'success';
if (progress >= 0.5) return 'info';
return 'warning';
};
return (
<Layout style={{ padding: 20, gap: 16 }}>
<Layout style={{ alignItems: 'center' }}>
<CircularProgressBar
progress={progress}
status={getStatus()}
size='large'
/>
<Text category='h6' style={{ marginTop: 8 }}>
{completedCount} of {tasks.length} tasks
</Text>
</Layout>
<Layout style={{ gap: 8 }}>
{tasks.map(task => (
<CheckBox
key={task.id}
checked={task.completed}
onChange={() => toggleTask(task.id)}
>
{task.title}
</CheckBox>
))}
</Layout>
</Layout>
);
};
Storage Usage Indicator
import React from 'react';
import { CircularProgressBar, Layout, Text } from '@ui-kitten/components';
const StorageUsageIndicator = () => {
const usedGB = 7.3;
const totalGB = 10;
const progress = usedGB / totalGB;
const getStatus = () => {
if (progress >= 0.9) return 'danger';
if (progress >= 0.7) return 'warning';
return 'success';
};
return (
<Layout style={{ alignItems: 'center', padding: 20 }}>
<Text category='h6'>Storage</Text>
<CircularProgressBar
progress={progress}
status={getStatus()}
size='giant'
style={{ marginVertical: 16 }}
/>
<Text category='s1'>
{usedGB.toFixed(1)} GB of {totalGB} GB used
</Text>
<Text appearance='hint'>
{(totalGB - usedGB).toFixed(1)} GB remaining
</Text>
</Layout>
);
};
Custom Text Styling
import { CircularProgressBar } from '@ui-kitten/components';
const StyledCircularProgress = () => (
<CircularProgressBar
progress={0.85}
status='success'
textStyle={{
fontSize: 24,
fontWeight: 'bold',
}}
/>
);
Without Animation
import { CircularProgressBar } from '@ui-kitten/components';
const StaticCircularProgress = () => (
<CircularProgressBar
progress={0.5}
animating={false}
/>
);
Theming
The CircularProgressBar component can be customized using Eva Design System theming. You can override:
- Track and indicator colors
- Track width
- Icon size
- Text styling (font family, size, weight)
- Component dimensions
Progress values are automatically clamped between 0 and 1. Values outside this range will be adjusted to the nearest valid value.
Accessibility
- The component automatically displays percentage text for screen readers
- When using custom icons, ensure they have appropriate accessibility labels
- Use color and text/icon together to convey status (not color alone)
- Consider adding descriptive labels above or below the progress indicator
Related Components
