FormCheck

A native checkbox with a visible label, semantic tone and a two-way boolean ref.

FormCheck

View source · API reference

Notification preferences

Toggle each independent preference. The required security setting demonstrates a checked, disabled state.

<RegorApp id="form-check-demo" src="./playground.ts"/>
import {
  defineFlexComponents,
  defineFormComponents,
} from '@purestack/ts-components'

import { createApp, defineComponent, html, type Ref, ref } from 'regor'

export interface FormCheckExample {
  emailUpdates: Ref<boolean>
  productUpdates: Ref<boolean>
}

const formCheckExampleTemplate = html`<Flex direction="column">
  <fieldset class="p-3 m-0">
    <legend>Notification preferences</legend>
    <Flex direction="column" align="start">
      <FormCheck
        id="check-email"
        name="updates"
        value="email"
        label="Email summaries"
        :checked="emailUpdates"
      />
      <FormCheck
        id="check-product"
        name="updates"
        value="product"
        label="Product updates"
        :checked="productUpdates"
      />
      <FormCheck
        id="check-security"
        label="Security alerts · required"
        :checked="true"
        :disabled="true"
      />
    </Flex>
  </fieldset>
  <FormStatus>
    Email summaries: {{ emailUpdates ? 'On' : 'Off' }} · Product updates: {{
    productUpdates ? 'On' : 'Off' }}
  </FormStatus>
</Flex>`

function createFormCheckExample(): FormCheckExample {
  return { emailUpdates: ref(true), productUpdates: ref(false) }
}

const component = defineComponent<FormCheckExample>(formCheckExampleTemplate, {
  context: createFormCheckExample,
})

createApp(
  {
    components: {
      FormCheckExample: component,

      ...defineFlexComponents(),
      ...defineFormComponents(),
    },
  },
  { selector: 'app#form-check-demo', template: html`<FormCheckExample />` },
)

A compact labelled checkbox

A checkbox without visible label text still needs an accessible name.

Example row 
<Flex align="center">
  <FormCheck id="check-compact" aria-label="Select this example row" tone="accent" />
  <span>Example row</span>
</Flex>

Behavior and accessibility

Press Space while focused to toggle. Group related choices in fieldset with a legend. Unchecked and disabled checkboxes are omitted from native form data. Supply checked as a writable boolean ref for two-way state.

API reference

FormCheck contract

Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.

id

string
Default
generated

Unique control ID. Supply an explicit value when help text or another element needs to reference this control.

label

RefOrValue<string>
Default
not set

Visible label. Use language that describes the control or value in its surrounding context.

name

RefOrValue<string>
Default
not set

Native form field name used during FormData serialization.

value

RefOrValue<string>
Default
browser default: on

Submitted value when checked. This is independent of the checked boolean.

checked

Ref<boolean>
Default
ref(false)

Writable boolean ref. Literal initial values are normalized into an internal ref.

disabled

RefOrValue<boolean>
Default
false

Disables interaction. Use a bound boolean, for example :disabled="isLocked".

tone

RefOrValue<SemanticTone>
Default
inherited

Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.

rootClass

RefOrValue<string>
Default
not set

Additional classes for the outer label, while inherited native attributes target the checkbox input.

Composition

No slots. label provides visible text. Register defineFormComponents or register FormCheck with defineFormCheckComponent.