hb-input-checkbox

Category: inputs · Tags: inputs

Summary

Labeled checkbox or Bulma switch (params.type === "switch") from schemaentry. Emits setVal on checked/validity changes. Missing or invalid schemaentry → nothing rendered.

schemaentry is typed as optional string | FormSchemaEntry for HTML vs JS; the control appears once a valid field is parsed.

Custom element

<hb-input-checkbox></hb-input-checkbox>

Tag name: hb-input-checkbox

Attributes (host)

Web component attributes use snake_case. Values exposed through HTML attributes are strings (including JSON for structured data and yes / no for booleans where noted).

| Attribute | Required | Description | |-----------|----------|-------------| | schemaentry | Yes (for visible UI) | JSON string (HTML) or object (JS). Must include a string id when parsed. See Schema (schemaentry) below. | | show_validation | No | yes or no (default no). When yes, a required but unchecked field shows validationTip inside the shadow tree and the host gets an invalid outline. | | id | No | Optional id on the custom element host. | | style | No | Optional inline styles on the host element. |

Schema (schemaentry)

The TypeScript shape is built from shared form row fields plus checkbox-specific params. At minimum, provide id. Other keys are optional unless you need labels, defaults, or validation UX.

| Key | Description | |-----|-------------| | id | Stable field identifier. Used in setVal payloads and as the native control id. | | label | Text beside the control. A * is appended when required is true. | | required | When true, valid is false until the control is checked. | | value | Initial / synced value: boolean, number, or string (coerced to boolean with JavaScript truthiness when applied). | | validationTip | Message shown when show_validation is yes, required is true, and the box is unchecked. | | disabled | When true, the input is disabled and not interactive. | | readonly | When true, the input is disabled for interaction (same net effect as disabled for the native control). | | placeholder | Allowed by the shared schema; this checkbox implementation does not render a separate placeholder control. | | params | See Switch mode (params.type). |

Switch mode (params.type)

Optional params object:

| Key | Values | Description | |-----|--------|-------------| | type | "switch" (or omit / other for default) | When "switch", the native checkbox is styled as a Bulma-colored switch (track and knob). Otherwise a standard checkbox appearance is used. |

TypeScript

types/webcomponent.type.d.ts — InputCheckboxParams, FormSchemaEntry, Component, Events.

Validation and events

Validity: If required is true, valid is true only when the control is checked. If required is false or omitted, valid is always true.

setVal custom event: Fired when value, valid, or the field id changes, after internal de-duplication of identical payloads.

| Property | Type | Description | |----------|------|-------------| | detail.value | boolean | Current checked state. | | detail.valid | boolean | Whether the field satisfies required. | | detail.id | string | The schemaentry.id. |

Listen in HTML or script:

<hb-input-checkbox id="terms"></hb-input-checkbox>
<script>
  document.getElementById("terms").addEventListener("setVal", (e) => {
    console.log(e.detail); // { value, valid, id }
  });
</script>

Styling

Styles use Bulma 1.x Sass inside the shadow root. The bundle forwards Bulma form layers form/shared, form/input-textarea, form/checkbox-radio, and form/tools, then applies the light theme on :host (see styles/bulma.scss). Component-specific layout and switch visuals are in styles/webcomponent.scss.

Theme the host with Bulma CSS variables (see Bulma: CSS variables).

Documented --bulma-* tokens for this package (from extra/docs.ts / styleSetup.vars):

| Variable | Role | |----------|------| | --bulma-text | Label text next to the checkbox or switch. | | --bulma-border | Checkbox border and switch track border. | | --bulma-link | Switch “on” fill and border when params.type is "switch". | | --bulma-danger | Invalid outline and danger help text when validation is shown. | | --bulma-radius | Corner radius for the switch track area. | | --bulma-radius-rounded | Pill radius for the circular switch knob. |

Switch styling also reads optional greys / scheme variables (for example --bulma-grey-*, --bulma-scheme-*, --bulma-white, --bulma-input-*) as fallbacks in styles/webcomponent.scss.

CSS parts (::part)

| Part | Description | |------|-------------| | input | The native checkbox input (standard mode) or the same element styled as the switch track and knob (switch mode). | | invalid-feedback | The p.help.is-danger paragraph when show_validation is yes and the required field is invalid. |

Slots

None.

Examples

Required agreement checkbox

<hb-input-checkbox
  schemaentry='{"id":"accept","label":"I agree to the terms","required":true,"validationTip":"You must accept to continue."}'
  show_validation="yes"
></hb-input-checkbox>

Pre-checked optional subscription

<hb-input-checkbox
  schemaentry='{"id":"newsletter","label":"Email me updates","required":false,"value":true}'
></hb-input-checkbox>

Switch UI

<hb-input-checkbox
  schemaentry='{"id":"notifications","label":"Enable notifications","params":{"type":"switch"},"value":false}'
></hb-input-checkbox>

Disabled / locked state

<hb-input-checkbox
  schemaentry='{"id":"locked","label":"Terms accepted","value":true,"disabled":true}'
></hb-input-checkbox>

Package metadata

• npm scope / repo name: @htmlbricks/hb-input-checkbox (see extra/docs.ts)
• License: Apache-2.0 (see extra/docs.ts → licenses)