# Checklists

Create task lists with boolean or enum statuses

Canonical URL: https://docs.paradoc.dev/guides/checklists/

This guide walks through creating a checklist with items, filling it with data, and rendering the output.

## Define the Checklist

A checklist needs a name, version, title, and items. Each item has an ID, title, and status configuration.



**Object Pattern**

```ts
import { p } from '@paradoc/sdk'

const onboarding = p.checklist({
  name: 'employee-onboarding',
  version: '1.0.0',
  title: 'Employee Onboarding Checklist',
  items: [
    { id: 'signed-contract', title: 'Signed Employment Contract', status: { kind: 'boolean' } },
    { id: 'received-equipment', title: 'Received Equipment', status: { kind: 'boolean' } },
    { id: 'completed-training', title: 'Completed Training', status: { kind: 'boolean' } },
  ],
})
```

**Builder Pattern**

```ts
import { p } from '@paradoc/sdk'

const onboarding = p
  .checklist()
  .name('employee-onboarding')
  .version('1.0.0')
  .title('Employee Onboarding Checklist')
  .items([
    { id: 'signed-contract', title: 'Signed Employment Contract', status: { kind: 'boolean' } },
    { id: 'received-equipment', title: 'Received Equipment', status: { kind: 'boolean' } },
    { id: 'completed-training', title: 'Completed Training', status: { kind: 'boolean' } },
  ])
  .build()
```

## Use Enum Statuses

Items can use enum statuses for multi-state workflows.



**Object Pattern**

```ts
const approvals = p.checklist({
  name: 'approval-workflow',
  version: '1.0.0',
  title: 'Approval Workflow',
  items: [
    {
      id: 'manager-approval',
      title: 'Manager Approval',
      status: {
        kind: 'enum',
        options: [
          { value: 'pending', label: 'Pending' },
          { value: 'approved', label: 'Approved' },
          { value: 'rejected', label: 'Rejected' },
        ],
      },
    },
    {
      id: 'hr-approval',
      title: 'HR Approval',
      status: {
        kind: 'enum',
        options: [
          { value: 'pending', label: 'Pending' },
          { value: 'approved', label: 'Approved' },
          { value: 'rejected', label: 'Rejected' },
        ],
      },
    },
  ],
})
```

**Builder Pattern**

```ts
const approvals = p
  .checklist()
  .name('approval-workflow')
  .version('1.0.0')
  .title('Approval Workflow')
  .items([
    {
      id: 'manager-approval',
      title: 'Manager Approval',
      status: {
        kind: 'enum',
        options: [
          { value: 'pending', label: 'Pending' },
          { value: 'approved', label: 'Approved' },
          { value: 'rejected', label: 'Rejected' },
        ],
      },
    },
    {
      id: 'hr-approval',
      title: 'HR Approval',
      status: {
        kind: 'enum',
        options: [
          { value: 'pending', label: 'Pending' },
          { value: 'approved', label: 'Approved' },
          { value: 'rejected', label: 'Rejected' },
        ],
      },
    },
  ])
  .build()
```

## Fill the Checklist

Use `.fill()` to create a draft checklist with item values.

```ts
const draft = onboarding.fill({
  'signed-contract': true,
  'received-equipment': true,
  'completed-training': false,
})

// Access individual items
console.log(draft.getItem('signed-contract')) // true

// Get all items
console.log(draft.getAllItems())
// { 'signed-contract': true, 'received-equipment': true, 'completed-training': false }
```

For enum checklists:

```ts
const draft = approvals.fill({
  'manager-approval': 'approved',
  'hr-approval': 'pending',
})
```

## Update Items

Use `.setItem()` to update individual items immutably.

```ts
// Create a new draft with updated item
const updated = draft.setItem('completed-training', true)

console.log(updated.getItem('completed-training')) // true
console.log(draft.getItem('completed-training')) // false (original unchanged)
```

## Add a Layer

Add a layer to render the checklist in a specific format.



**Object Pattern**

```ts
const onboarding = p.checklist({
  name: 'employee-onboarding',
  version: '1.0.0',
  title: 'Employee Onboarding Checklist',
  items: [
    { id: 'signed-contract', title: 'Signed Employment Contract', status: { kind: 'boolean' } },
    { id: 'received-equipment', title: 'Received Equipment', status: { kind: 'boolean' } },
    { id: 'completed-training', title: 'Completed Training', status: { kind: 'boolean' } },
  ],
  defaultLayer: 'markdown',
  layers: {
    markdown: {
      kind: 'inline',
      mimeType: 'text/markdown',
      text: `
# Employee Onboarding Checklist

- [{{#if items["signed-contract"]}}x{{else}} {{/if}}] Signed Employment Contract
- [{{#if items["received-equipment"]}}x{{else}} {{/if}}] Received Equipment
- [{{#if items["completed-training"]}}x{{else}} {{/if}}] Completed Training
      `,
    },
  },
})
```

**Builder Pattern**

```ts
const onboarding = p
  .checklist()
  .name('employee-onboarding')
  .version('1.0.0')
  .title('Employee Onboarding Checklist')
  .items([
    { id: 'signed-contract', title: 'Signed Employment Contract', status: { kind: 'boolean' } },
    { id: 'received-equipment', title: 'Received Equipment', status: { kind: 'boolean' } },
    { id: 'completed-training', title: 'Completed Training', status: { kind: 'boolean' } },
  ])
  .inlineLayer('markdown', {
    mimeType: 'text/markdown',
    text: `
# Employee Onboarding Checklist

- [{{#if items["signed-contract"]}}x{{else}} {{/if}}] Signed Employment Contract
- [{{#if items["received-equipment"]}}x{{else}} {{/if}}] Received Equipment
- [{{#if items["completed-training"]}}x{{else}} {{/if}}] Completed Training
    `,
  })
  .defaultLayer('markdown')
  .build()
```

## Render the Checklist

Render the filled checklist using a renderer.

```ts
import { createLayerRenderer } from '@paradoc/render'

const draft = onboarding.fill({
  'signed-contract': true,
  'received-equipment': true,
  'completed-training': false,
})

const output = await draft.render({ renderer: createLayerRenderer() })
console.log(output)
```

Output:

```markdown
# Employee Onboarding Checklist

- [x] Signed Employment Contract
- [x] Received Equipment
- [ ] Completed Training
```

## Save the Artifact

Export the checklist to JSON or YAML for storage or version control.

```ts
const json = onboarding.toJSON()
const yaml = onboarding.toYAML()
```



**JSON**

```json
{
  "$schema": "https://schema.paradoc.dev/2026-10-02.json",
  "kind": "checklist",
  "name": "employee-onboarding",
  "version": "1.0.0",
  "title": "Employee Onboarding Checklist",
  "items": [
    {
      "id": "signed-contract",
      "title": "Signed Employment Contract",
      "status": { "kind": "boolean" }
    },
    {
      "id": "received-equipment",
      "title": "Received Equipment",
      "status": { "kind": "boolean" }
    },
    {
      "id": "completed-training",
      "title": "Completed Training",
      "status": { "kind": "boolean" }
    }
  ]
}
```

**YAML**

```yaml
$schema: https://schema.paradoc.dev/2026-10-02.json
kind: checklist
name: employee-onboarding
version: 1.0.0
title: Employee Onboarding Checklist
items:
  - id: signed-contract
    title: Signed Employment Contract
    status:
      kind: boolean
  - id: received-equipment
    title: Received Equipment
    status:
      kind: boolean
  - id: completed-training
    title: Completed Training
    status:
      kind: boolean
```

Load it back with `p.load()`:

```ts
const loaded = p.load(jsonString) // works with JSON or YAML
```