# Checklist

> Steps towards something, ticked off as they're done.

- Import: `import { Checklist } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-checklist--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Checklist/Checklist.vue

## When to use

- Showing what's left before a form can be submitted, or a setup's progress (e.g. New School Year Setup's summary).

## When not to use

- Things people tick themselves: use Checkbox.
- A sequence people move through page by page: a stepper (not in the library yet).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| item | Yes | An icon and a label. |
| icon | Yes | Done: green circled tick. To do: empty grey circle. 16px. |
| label | Yes | Done: black. To do: black 65%. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| items | { label, done }[] | — | Required. Labels must be unique. |

## Spacing and layout

- Items 8px apart; icon to label 8px. The icon stays level with the first line of a label that wraps.
- Usually in a summary Card beside a form.

## Accessibility

- A `<ul>`; each item adds "(done)" or "(to do)" for screen readers, as the icon is decorative.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Checklist.vue` | — |
| iOS (SwiftUI) | — | `Label` rows with `checkmark.circle.fill` / `circle`. |
| Android (Compose) | — | Rows with `CheckCircle` / `RadioButtonUnchecked` icons. |

## Tokens used

| Token | Used for |
|---|---|
| `color-green` | Done icon |

## Do / Don't

| Do | Don't |
|---|---|
| Name each step by its part of the page ("Term dates"). | Write instructions ("You need to add term dates"). |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Checklist.vue
/**
 * Steps towards something, ticked off as they're done: what's left before a
 * form can be submitted, or setting up a new school year. It shows progress;
 * people don't tick it themselves (use Checkbox for that).
 */
export interface ChecklistItem {
  /** What needs doing, e.g. "Term dates". */
  label: string
  done: boolean
}

export interface ChecklistProps {
  items: ChecklistItem[]
  class?: HTMLAttributes['class']
}
```