TaskList component for Stripe Apps
Use TaskList to help users track their progress through a list of tasks they must complete.
Warning
To add the TaskList component to your app:
import {TaskList, TaskListItem} from '@stripe/ui-extension-sdk/ui';
Use TaskList:
- To break larger tasks or processes into multiple, sequential steps for a user to complete
- To remind users of their progress on unfinished tasks
Task lists consist of individual items. You can nest task lists within task list items to represent sub-tasks. When a user completes a task, stop showing its sub-tasks. You can either hide them completely if they’re no longer useful or allow the user to click to reveal them.
The following example demonstrates how to render a task list with a connector line to reinforce a requirement to complete tasks sequentially.
const tasks: TaskListItemProps[] = [ { title: 'Add business info', status: 'complete', }, { title: 'Connect your bank', status: 'complete', }, { title: 'Secure your account', status: 'complete', }, { title: 'Add extras', status: 'in-progress', subTasks: [ { title: 'Tax calculation', status: 'complete', }, { title: 'Fraud protection', status: 'in-progress', }, { title: 'Climate contributions', status: 'not-started', }, ], }, { title: 'Review and finish', status: 'not-started', }, ]; return ( <TaskList> {tasks.map((task, idx) => ( <TaskListItem key={idx} {...task} /> ))} </TaskList> )
TaskList props
| Property | Type |
|---|---|
| Required
One or more |
TaskListItem
TaskList components contain one or more TaskListItem components that define each task the user must complete. If a task list item defines its own sub-tasks, a user must complete those sub-tasks to complete the parent task.
TaskListItem props
| Property | Type |
|---|---|
| Required
The display title of the task. |
| Optional
An event handler for when the user clicks anywhere on the task. |
| Optional
The current status of the task. |
| Optional
A list of sub-tasks that belong to this task. Related types: SubTasks. |
SubTasks
| Property | Type |
|---|---|
| Required
The display title of the task. |
| Optional
An event handler for when the user clicks anywhere on the task. |
| Optional
The current status of the task. |
Stateful
The following example demonstrates how to render a stateful task list, where the status of each task item is updated in response to a click event.
import {useReducer, useCallback} from 'react'; import { Box, Button, TaskList, TaskListItem, TaskListItemProps, } from '@stripe/ui-extension-sdk/ui'; const initialTasks: TaskListItemProps[] = [ { title: 'Add business info', status: 'in-progress', }, { title: 'Connect your bank', status: 'complete', }, { title: 'Secure your account', status: 'complete', }, { title: 'Add extras', status: 'in-progress', subTasks: [ { title: 'Tax calculation', status: 'in-progress', }, { title: 'Fraud protection', status: 'in-progress', }, { title: 'Climate contributions', status: 'not-started', }, ], }, { title: 'Review and finish', status: 'not-started', }, ]; const [tasks, dispatch] = useReducer(taskReducer, initialTasks); const toggleStatus = useCallback((taskIdx: number, subTaskIdx?: number) => { dispatch({type: 'TOGGLE_STATUS', taskIdx, subTaskIdx}); }, []); return ( <Box> <TaskList> {tasks.map((task, taskIdx) => ( <TaskListItem key={`task-${taskIdx}-${task.status}`} {...task} onPress={() => toggleStatus(taskIdx)} subTasks={task.subTasks?.map((subTask, subTaskIdx) => ({ ...subTask, onPress: () => toggleStatus(taskIdx, subTaskIdx), }))} /> ))} </TaskList> </Box> ); function getNextStatus( status: string, ): 'not-started' | 'in-progress' | 'complete' { switch (status) { case 'complete': return 'not-started'; case 'not-started': return 'in-progress'; case 'in-progress': return 'complete'; default: return 'not-started'; } } type TaskAction = { type: 'TOGGLE_STATUS'; taskIdx: number; subTaskIdx?: number; }; // Reducer function to handle state updates function taskReducer( state: TaskListItemProps[], action: TaskAction, ): TaskListItemProps[] { switch (action.type) { case 'TOGGLE_STATUS': // If subTaskId is provided, update the subtask if (action.subTaskIdx !== undefined) { return state.map((task, idx) => { if (idx === action.taskIdx && task.subTasks) { return { ...task, subTasks: task.subTasks.map((subTask, subIdx) => { if (subIdx === action.subTaskIdx) { return { ...subTask, status: getNextStatus(subTask.status as string), }; } return subTask; }), }; } return task; }); } // Otherwise update the main task else { return state.map((task, idx) => { if (idx === action.taskIdx) { return { ...task, status: getNextStatus(task.status as string), }; } return task; }); } default: return state; } }