Tessera UI

Components

Checkbox

A choice that is on or off. Press it, or use Space.

The preview needs JavaScript. The code is in the Code tab.

Checkbox-0.tess
<template>
  <div>
    <Checkbox>Send me product news</Checkbox>
    <Checkbox checked>Remember me</Checkbox>
    <Checkbox disabled>Not available</Checkbox>
  </div>
</template>

Installation

npx @pixelscriptio/tessera add Checkbox
pnpm exec tessera add Checkbox
yarn tessera add Checkbox
bunx @pixelscriptio/tessera add Checkbox
  • Works with Tessera 0.9.0 or newer.
  1. Copy and paste the code into your project

    Put it in system/components.

    system/components/Checkbox.tess
    <contract>
    {
      "name": "Checkbox",
      "role": "checkbox",
      "description": "A choice that is on or off. Press it, or use Space.",
      "since": "0.5.0",
      "parts": ["root", "box", "mark", "label"],
      "variants": {
        "size": ["md", "sm"] // first value is the default
      },
      "states": ["hover", "focus-visible", "checked", "disabled"],
      "behavior": "toggle",
      "slots": {
        "default": "the label"
      },
      "events": {
        "toggle": "fired with { checked, source } when the person changes it; the checked prop sets it from outside"
      },
      "preview": {
        "slots": {
          "default": "Remember me"
        }
      }
    }
    </contract>
    
    <script>
    const { checked, disabled } = props({ checked: false, disabled: false })
    
    // The component owns the state, starts from the prop and follows it when it changes.
    const on = state(checked.value)
    effect(() => {
      on.value = checked.value
    })
    
    function change(detail) {
      on.value = detail.checked
      emit('toggle', detail)
    }
    </script>
    
    <template>
      <button
        class="root"
        type="button"
        role="checkbox"
        :aria-checked="on ? 'true' : 'false'"
        :disabled="disabled"
        @toggle="change($event)"
        >
        <span class="box"><span class="mark" aria-hidden="true">โœ“</span></span>
        <span class="label"><slot /></span>
      </button>
    </template>
    
    <style>
    .root {
      display: inline-flex;
      align-items: center;
      gap: $space.2;
      padding: $space.1 0;
      border: 0;
      background: transparent;
      color: $color.text.default;
      font-family: var(--t-font-family-sans);
      font-size: $font.size.sm;
      cursor: pointer;
    
      &:focus-visible {
        outline: 2px solid $color.focus.ring;
        outline-offset: 2px;
      }
    
      &:disabled {
        opacity: $opacity.disabled;
        cursor: not-allowed;
      }
    
      &[data-size='sm'] {
        font-size: $font.size.sm;
      }
    }
    
    .box {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      width: $space.5;
      height: $space.5;
      border: 1px solid $color.border.strong;
      border-radius: $radius.sm;
      background: $color.surface.default;
      color: $color.action.primary.fg;
      transition-duration: $motion.duration.fast;
    }
    
    .root[data-size='sm'] .box {
      width: $space.4;
      height: $space.4;
    }
    
    .root:hover:not(:disabled) .box {
      background: $color.surface.hover;
    }
    
    .root[aria-checked='true'] .box {
      border-color: $color.action.primary.bg;
      background: $color.action.primary.bg;
    }
    
    .root[aria-checked='true']:hover:not(:disabled) .box {
      background: $color.action.primary.bg-hover;
    }
    
    .mark {
      visibility: hidden;
      font-size: $font.size.sm;
      line-height: 1;
    }
    
    .root[aria-checked='true'] .mark {
      visibility: visible;
    }
    
    .label:empty {
      display: none;
    }
    </style>
    
  2. Check your design tokens

    Your design system needs these. tessera add reports the ones that are missing; by hand, run npx @pixelscriptio/tessera check.

    color.action.primary.bg color.action.primary.bg-hover color.action.primary.fg color.border.strong color.focus.ring color.surface.default color.surface.hover color.text.default font.size.sm motion.duration.fast opacity.disabled radius.sm space.1 space.2 space.4 space.5

Usage

Using Checkbox

Use a checkbox when a person can pick any number of options, or must agree to something. For one setting that takes effect at once, use a Switch.

  • The label says what is chosen, not "Yes".
  • It starts unchecked. Set checked to start it checked, or to change it from outside.
  • The toggle event says where it is going: { checked, source }. The component keeps its own state, so you do not have to.
  • Space toggles it. Enter does not, as with a native checkbox.

The preview needs JavaScript. The code is in the Code tab.

Checkbox-0.tess
<template>
  <div>
    <Checkbox>Send me product news</Checkbox>
    <Checkbox checked>Remember me</Checkbox>
    <Checkbox disabled>Not available</Checkbox>
  </div>
</template>

API reference

Variants

VariantValues
sizemd default sm

Slots

SlotContent
defaultthe label

Events

EventWhen
togglefired with { checked, source } when the person changes it; the checked prop sets it from outside

Anatomy

Rolecheckbox
Behaviortoggle
Partsroot box mark label
Stateshover focus-visible checked disabled
Since0.5.0

Design tokens it uses

Your design system needs these. tessera add checks that it has them, and can add the ones it lacks.

color.action.primary.bg color.action.primary.bg-hover color.action.primary.fg color.border.strong color.focus.ring color.surface.default color.surface.hover color.text.default font.size.sm motion.duration.fast opacity.disabled radius.sm space.1 space.2 space.4 space.5

Checksum

c96b2b256a3631f80eb3c6ec384903ee663b85319dfe6c2dc8210dc3936189ef