@dopt/react-checklist

Overview

A React checklist component for building experiences with Dopt.

You can use the checklist component out of the box as a pre-built component or break out and use it headlessly with your own UI component.

Learn more about how to use this component with Dopt →

Installation

ℹ️ If you are using a particular React framework like Next.js, please check out our framework specific docs.

``bash

`npm`


npm install @dopt/react-checklist
Yarn

yarn add @dopt/react-checklist
pnpm

pnpm add @dopt/react-checklist


Usage

The default export from @dopt/react-checklist is a collection of components that you can use to structure and compose a checklist.

`jsx import Checklist, { useChecklist } from '@dopt/react-checklist';

function MyChecklist() { const checklist = useChecklist('checklist.pink-crews-clap');

return ( {checklist.title} {checklist.body} value={checklist.count('done')} max={checklist.size} /> {checklist.items.map((item, i) => ( {item.completed ? ( ) : item.skipped ? ( ) : ( )} {item.title}

{item.body}

{!item.done && ( {item.completeLabel} )} {!item.done && } ))} ); }`

Check out our checklist example and our headless checklist example for more in-depth usage.

`Props`

`$3`

The root element of the checklist. Extends HTMLElement.

| Name | Type | Description | | --------- | ------------------------------------------------------------------------ | --------------------------------------------- | | children? | ReactNode | The contents of the component | | theme? | Theme | A theme definition to attach to the component |

`$3`

The header of the checklist. Extends HTMLElement.

`$3`

The title of the checklist. Extends HTMLHeadingElement.

`$3`

The dismiss icon of the checklist. Extends HTMLButtonElement.

`$3`

The body of the tour item popover. Extends HTMLDivElement.

| Name | Type | Description | | --------- | ------------------------------------------------------------------------ | --------------------------------------------- | | children? | RichText | The rich text contents of the component | | theme? | Theme | A theme definition to attach to the component |

`$3`

The progress meter of the checklist. Extends HTMLDivElement.

| Name | Type | Description | | ------ | ------------------------------------------------------------------------ | -------------------------------------------------- | | max | number | The maximum number of items that can be progressed | | theme? | Theme | A theme definition to attach to the component | | value | number | The current number of items progressed |

`$3`

The items of the checklist. Extends HTMLUListElement.

`$3`

A checklist item. Extends HTMLLIElement.

| Name | Type | Description | | --------- | ------------------------------------------------------------------------ | --------------------------------------------- | | children? | ReactNode | The contents of the component | | index? | number | The index of the item | | theme? | Theme | A theme definition to attach to the component |

`$3`

The icon of a checklist item. Extends HTMLDivElement.

`$3`

The active icon. Extends SVGSVGElement.

`$3`

The completed icon. Extends SVGSVGElement.

`$3`

The skipped icon. Extends SVGSVGElement.

`$3`

The content of a checklist item. Extends HTMLDivElement.

`$3`

The title of a checklist item. Extends HTMLDivElement.

`$3`

The body of a checklist item. Extends HTMLDivElement.

| Name | Type | Description | | --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- | | children? | RichText | The rich text contents of the component | | theme? | Theme | A theme definition to attach to the component | | disabled? | boolean | Determines if the body is show as disabled (default:false) |

`$3`

The complete button of a checklist item. Extends HTMLButtonElement.

`$3`

The skip icon of a checklist item. Extends HTMLButtonElement.

`Hooks`

If you are planning to only use the checklist headlessly, you can import the hooks alone using @dopt/react-checklist/hooks.

`$3`

- useChecklist(id: string): Checklist

A React hook for managing a checklist's state and content.

`tsx import { useChecklist } from '@dopt/react-checklist'; import RichText from '@dopt/react-rich-text';

export function MyChecklist() { const { id, title, body, items, active, completed, dismissed, complete, dismiss, filter, count, size, } = useChecklist('onboarding-checklist.checklist-component');

return (


      
        checklist.active: {active}

        checklist.completed: {completed}

        checklist.dismissed: {dismissed}

      

      
        
        
      

      
        checklist.title: {title}

        
          checklist.body: {body}
        

      

      
        
          checklist.items: {JSON.stringify(items.map((item) => item.id))}
        

      

      
        {filter('completed')}

        {filter('not-completed')}

        {filter('skipped')}

        {filter('not-skipped')}

        {filter('active')}

        {filter('not-active')}

        {filter('done')}

        {filter('not-done')}

      

      
        {count('completed')}

        {count('not-completed')}

        {count('skipped')}

        {count('not-skipped')}

        {count('active')}

        {count('not-active')}

        {count('done')}

        {count('not-done')}

      

      
        checklist.size: {size}


  );
}

$3

- useChecklistItem(id: string): ChecklistItem

A React hook for managing a checklist item's state and content.

`tsx import { useChecklistItem } from '@dopt/react-checklist'; import RichText from '@dopt/react-rich-text';

export function MyChecklistItem() { const { id, index, title, body, completeLabel, done, active, skipped, completed, complete, skip, } = useChecklistItem("onboarding-checklist.item-1");

return (


      
        checklistItem.active: {active}

        checklistItem.skipped: {skipped}

        checklistItem.completed: {completed}

        checklistItem.done: {done}

      

      
        
        
      

      
        checklistItem.title: {title}

        checklistItem.body: {body}

        checklistItem.completeLabel: {completeLabel}

      

      
        checklistItem.index: {checklistItem.index}

)
}


Styling API
Learn more about styling and theming →

| Name | Selector | Description | | ---------------- | ------------------------------------- | ----------------------------------------------- | | root |.dopt-checklist| Root element | | header |.dopt-checklist__header| Header containing title, body, and dismiss icon | | title |.dopt-checklist__title| Title heading | | body |.dopt-checklist__body| Body content | | dismissIcon |.dopt-checklist__dismiss-icon| Dismiss icon button | | progress |.dopt-checklist__progress| Progress container | | progressMeter |.dopt-checklist__progress-meter| Progress meter | | progressMeterBar |.dopt-checklist__progress-meter-bar| Progress meter bar | | progressContent |.dopt-checklist__progress-content| Progress content | | items |.dopt-checklist__items | Items container |

`$3`

| Name | Selector | Description | | ------------------ | --------------------------------------- | --------------------------------------------------- | | item |.dopt-checklist__item| Item containing icon, content, and skip icon | | item |.dopt-checklist__item--$index| Item by index (starting at 1) | | itemIcon |.dopt-checklist__item-icon| State icon | | itemContent |.dopt-checklist__item-content| Content containing title, body, and complete button | | itemTitle |.dopt-checklist__item-title| Title heading | | itemBody |.dopt-checklist__item-body| Body content | | itemCompleteButton |.dopt-checklist__item-complete-button| Complete button | | itemSkipIcon |.dopt-checklist__item-skip-icon | Skip icon button |

`$3`

| Name | Selector | Description | | --------- | --------------------------------- | -------------- | | icon |.dopt-checklist__icon| Icon element | | active |.dopt-checklist__icon-active| Active icon | | completed |.dopt-checklist__icon-completed| Completed icon | | skipped |.dopt-checklist__icon-skipped | Skipped icon |

`Types`

`$3`

A stateful container for checklist items.

`ts interface Checklist { id: string;

title: string | null | undefined; body: RichText | null | undefined;

items: ChecklistItem[];

active: boolean;

completed: boolean; dismissed: boolean;

complete: () => void; dismiss: () => void;

size: number;

filter(on: FilterableField): ChecklistItem[]; count(where: CountableField): number; }`

`$3`

A child of the Checklist. Includes state accessors and methods for updating state along with content configured in Dopt.

`ts interface ChecklistItem { id: string;

index: number | null | undefined;

title: string | null | undefined; body: RichText | null | undefined;

completeLabel: string | null | undefined;

done: boolean;

active: boolean;

skipped: boolean; completed: boolean;

complete: () => void; skip: () => void; }`

`$3`

`$3`

`ts type CountableField = FilterableField;``