Checklist

A checklist control with change events and form integration.

Import

import { Checklist } from "@schukai/monster/source/components/form/checklist.mjs";

Source

View source code

Package

@schukai/monster

Since

1.0.0

Release readiness

Introduction

The Monster Checklist is a form-aware multi-selection control for short, task-oriented lists. Each item has a stable ID, a visible label and its own checked or disabled state. The component keeps its submitted form value in sync as a JSON array of checked item IDs.

When to use Checklist

Use it for independent choices: Preferences, permissions, preparation steps and acceptance criteria can be selected separately.
Use it when every option should remain visible: A compact checklist is easier to scan than a closed multi-select for a handful of items.
Use stable IDs as values: Labels may change, while IDs can remain safe for forms and application state.
Do not use it for ordered progress: If tasks must be completed in sequence, use a wizard or dedicated progress component.

Item model

Configure items with setItems(). Object items make checked and disabled states explicit; strings and numbers are accepted as shortcuts and receive generated IDs.

checklist.setItems([
  {id: "profile", label: "Complete profile", checked: true},
  {id: "review", label: "Review settings"},
  {id: "publish", label: "Publish workspace", disabled: true}
]);

Values and events

The value property returns the checked IDs. A user change emits the native change event and monster-checklist-change. Its detail contains the changed item, the complete normalized item list and the current value.

Typical mistakes

Do not use display labels as persistent identifiers. Keep every id unique and stable, and use the component's public value, getCheckedItems() and setItems() APIs instead of reaching into its Shadow DOM.

Checklist Basics

This example configures a form-aware monster-checklist with stable item IDs, initial selections and a named form value.

Workspace notifications

Javascript

import "@schukai/monster/source/components/form/checklist.mjs";

await customElements.whenDefined("monster-checklist");

const checklist = document.getElementById("notification-checklist");

checklist.setItems([
  { id: "mentions", label: "Mentions", checked: true },
  { id: "releases", label: "Release updates", checked: true },
  { id: "digest", label: "Weekly digest" },
]);

HTML

<section>
  <strong style="display: block; margin-bottom: 0.75rem"
    >Workspace notifications</strong
  >
  <monster-checklist
    id="notification-checklist"
    name="notifications"
  ></monster-checklist>
</section>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Checklist Selection State

Reads normalized checklist state with getCheckedItems() after public change events.

No checks completed.

Javascript

import "@schukai/monster/source/components/form/checklist.mjs";

const checklist = document.getElementById("release-checklist");
const status = document.getElementById("release-checklist-status");
checklist.setItems([
  {id: "tests", label: "Tests passed", checked: true},
  {id: "review", label: "Review completed"},
  {id: "deploy", label: "Deployment verified"},
]);
checklist.addEventListener("monster-checklist-change", () => {
  status.textContent = `${checklist.getCheckedItems().length} of ${checklist.getItems().length} completed.`;
});

HTML

<section style="display:grid;gap:var(--monster-space-3)">
  <monster-checklist id="release-checklist"></monster-checklist>
  <output id="release-checklist-status">No checks completed.</output>
</section>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Content and layout

Keep labels short enough to scan as a group and arrange related choices in a single checklist. If an option needs a long explanation, place supporting copy around the control instead of turning every row into a paragraph.

State communication

Checked state must not be the only feedback for a workflow. Pair the control with a concise status summary when completion count or selected values matter. Disabled items should remain exceptional and should be explained by nearby guidance when the reason is not obvious.

Customizing With Parts

You can adapt the visual appearance through exported parts instead of modifying the internal template. This reference is generated from the current component source.

The component exposes these part names:

checkbox: Element representing the checkbox.
control: Outer wrapper of the component.
item: Element representing the item.
items: Element representing the items.
label: Visible label element.

HTML Structure

<monster-checklist></monster-checklist>

JavaScript Initialization

const element = document.createElement('monster-checklist');
document.body.appendChild(element);

Exported

Checklist

Derived from

CustomControl

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomControl.

Option

Type

Default

Description

items

array

undefined

The checklist items.

disabled

boolean

false

Disabled state.

templates

object

Template definitions.

templates.main

string

undefined

Main template.

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomControl.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomControl.

State query methods

value()

Returns

{Array}

No description available.

value(value)

Parameters

value {array}: value

No description available.

Structural methods

getCheckedItems()

Returns

{Array}

No description available.

getItems()

Returns

{Array}

No description available.

setItems(items)

Parameters

items {array}: items

Returns

{Checklist}

No description available.

Static methods

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

No description available.

getTag()

Returns

{string}

No description available.

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{void}

No description available.

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.