11.0.1 • Published 7 days ago

@dopt/react-checklist v11.0.1

Weekly downloads
-
License
MIT
Repository
github
Last release
7 days ago

@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.

# 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.

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

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

  return (
    <Checklist.Root>
      <Checklist.Header>
        <Checklist.Title>{checklist.title}</Checklist.Title>
        <Checklist.DismissIcon onClick={checklist.dismiss} />
      </Checklist.Header>
      <Checklist.Body>{checklist.body}</Checklist.Body>
      <Checklist.Progress
        value={checklist.count('done')}
        max={checklist.size}
      />
      <Checklist.Items>
        {checklist.items.map((item, i) => (
          <Checklist.Item key={i}>
            <Checklist.ItemIcon>
              {item.completed ? (
                <Checklist.IconCompleted />
              ) : item.skipped ? (
                <Checklist.IconSkipped />
              ) : (
                <Checklist.IconActive />
              )}
            </Checklist.ItemIcon>
            <Checklist.ItemContent>
              <Checklist.ItemTitle disabled={item.done}>
                {item.title}
              </Checklist.ItemTitle>

              <Checklist.ItemBody disabled={item.done}>
                {item.body}
              </Checklist.ItemBody>

              {!item.done && (
                <Checklist.ItemCompleteButton onClick={item.complete}>
                  {item.completeLabel}
                </Checklist.ItemCompleteButton>
              )}
            </Checklist.ItemContent>
            {!item.done && <Checklist.ItemSkipIcon onClick={item.skip} />}
          </Checklist.Item>
        ))}
      </Checklist.Items>
    </Checklist.Root>
  );
}

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

Props

Root

The root element of the checklist. Extends HTMLElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Header

The header of the checklist. Extends HTMLElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Title

The title of the checklist. Extends HTMLHeadingElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

DismissIcon

The dismiss icon of the checklist. Extends HTMLButtonElement.

NameTypeDescription
theme?ThemeA theme definition to attach to the component

Body

The body of the tour item popover. Extends HTMLDivElement.

NameTypeDescription
children?RichTextThe rich text contents of the component
theme?ThemeA theme definition to attach to the component

Progress

The progress meter of the checklist. Extends HTMLDivElement.

NameTypeDescription
maxnumberThe maximum number of items that can be progressed
theme?ThemeA theme definition to attach to the component
valuenumberThe current number of items progressed

Items

The items of the checklist. Extends HTMLUListElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Item

A checklist item. Extends HTMLLIElement.

NameTypeDescription
children?ReactNodeThe contents of the component
index?numberThe index of the item
theme?ThemeA theme definition to attach to the component

ItemIcon

The icon of a checklist item. Extends HTMLDivElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

IconActive

The active icon. Extends SVGSVGElement.

IconCompleted

The completed icon. Extends SVGSVGElement.

IconSkipped

The skipped icon. Extends SVGSVGElement.

ItemContent

The content of a checklist item. Extends HTMLDivElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

ItemTitle

The title of a checklist item. Extends HTMLDivElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

ItemBody

The body of a checklist item. Extends HTMLDivElement.

NameTypeDescription
children?RichTextThe rich text contents of the component
theme?ThemeA theme definition to attach to the component
disabled?booleanDetermines if the body is show as disabled (default: false)

CompleteButton

The complete button of a checklist item. Extends HTMLButtonElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

SkipIcon

The skip icon of a checklist item. Extends HTMLButtonElement.

NameTypeDescription
theme?ThemeA theme definition to attach to the component

Hooks

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

useChecklist

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

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 (
    <div>
      <div id="states">
        <div>checklist.active: {active}</div>
        <div>checklist.completed: {completed}</div>
        <div>checklist.dismissed: {dismissed}</div>
      </div>
      <div id="actions">
        <button onClick={complete}>Complete</button>
        <button onClick={dismiss}>Dismiss</button>
      </div>
      <div id="content">
        <div>checklist.title: {title}</div>
        <div>
          checklist.body: <RichText.Root>{body}</RichText.Root>
        </div>
      </div>
      <div id="children">
        <div>
          checklist.items: {JSON.stringify(items.map((item) => item.id))}
        </div>
      </div>
      <div id="filtering">
        <div id="f-completed">{filter('completed')}</div>
        <div id="f-not-completed">{filter('not-completed')}</div>
        <div id="f-skipped">{filter('skipped')}</div>
        <div id="f-not-skipped">{filter('not-skipped')}</div>
        <div id="f-active">{filter('active')}</div>
        <div id="f-not-active">{filter('not-active')}</div>
        <div id="f-done">{filter('done')}</div>
        <div id="f-not-done">{filter('not-done')}</div>
      </div>
      <div id="counting">
        <div id="c-completed">{count('completed')}</div>
        <div id="c-not-completed">{count('not-completed')}</div>
        <div id="c-skipped">{count('skipped')}</div>
        <div id="c-not-skipped">{count('not-skipped')}</div>
        <div id="c-active">{count('active')}</div>
        <div id="c-not-active">{count('not-active')}</div>
        <div id="c-done">{count('done')}</div>
        <div id="c-not-done">{count('not-done')}</div>
      </div>
      <div id="metadata">
        <div>checklist.size: {size}</div>
      </div>
    </div>
  );
}

useChecklistItem

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

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 (
    <div>
      <div id="states">
        <div>checklistItem.active: {active}</div>
        <div>checklistItem.skipped: {skipped}</div>
        <div>checklistItem.completed: {completed}</div>
        <div>checklistItem.done: {done}</div>
      </div>
      <div id="actions">
        <button onClick={complete}>{completeLabel}</button>
        <button onClick={skip}>Skip</button>
      </div>
      <div id="content">
        <div>checklistItem.title: {title}</div>
        <div>checklistItem.body: <RichText.Root>{body}</RichText.Root></div>
        <div>checklistItem.completeLabel: {completeLabel}</div>
      </div>
      <div id="metadata">
        <div>checklistItem.index: {checklistItem.index}</div>
      </div>
    <div>
  )
}

Styling API

Learn more about styling and theming →

NameSelectorDescription
root.dopt-checklistRoot element
header.dopt-checklist__headerHeader containing title, body, and dismiss icon
title.dopt-checklist__titleTitle heading
body.dopt-checklist__bodyBody content
dismissIcon.dopt-checklist__dismiss-iconDismiss icon button
progress.dopt-checklist__progressProgress container
progressMeter.dopt-checklist__progress-meterProgress meter
progressMeterBar.dopt-checklist__progress-meter-barProgress meter bar
progressContent.dopt-checklist__progress-contentProgress content
items.dopt-checklist__itemsItems container

Item

NameSelectorDescription
item.dopt-checklist__itemItem containing icon, content, and skip icon
item.dopt-checklist__item--$indexItem by index (starting at 1)
itemIcon.dopt-checklist__item-iconState icon
itemContent.dopt-checklist__item-contentContent containing title, body, and complete button
itemTitle.dopt-checklist__item-titleTitle heading
itemBody.dopt-checklist__item-bodyBody content
itemCompleteButton.dopt-checklist__item-complete-buttonComplete button
itemSkipIcon.dopt-checklist__item-skip-iconSkip icon button

Icon

NameSelectorDescription
icon.dopt-checklist__iconIcon element
active.dopt-checklist__icon-activeActive icon
completed.dopt-checklist__icon-completedCompleted icon
skipped.dopt-checklist__icon-skippedSkipped icon

Types

Checklist

A stateful container for checklist items.

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;
}

ChecklistItem

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

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;
}

FilterableField

type FilterableField =
  | 'completed'
  | 'not-completed'
  | 'skipped'
  | 'not-skipped'
  | 'active'
  | 'not-active'
  | 'done'
  | 'not-done';

CountableField

type CountableField = FilterableField;
11.0.1

7 days ago

10.0.1

19 days ago

11.0.0

13 days ago

9.0.5

2 months ago

9.0.4

2 months ago

9.0.3

2 months ago

9.0.2

3 months ago

9.0.1

3 months ago

9.0.0

6 months ago

8.1.0

7 months ago

8.0.1

7 months ago

8.0.0

7 months ago

7.0.5

7 months ago

7.0.4

8 months ago

7.0.3

8 months ago

7.0.2

8 months ago

7.0.1

8 months ago

7.0.0

8 months ago

6.2.0

9 months ago

6.1.0

9 months ago

6.0.0

9 months ago

5.0.2

9 months ago

5.0.1

9 months ago

5.0.0

9 months ago

4.1.0

9 months ago

4.0.1

9 months ago

4.0.0

9 months ago

3.0.0

10 months ago

2.0.0

10 months ago

1.0.6

10 months ago

1.0.5

10 months ago

1.0.4

10 months ago

1.0.3

10 months ago

1.0.2

10 months ago

1.0.1

10 months ago

1.0.0

10 months ago