Page History
(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)
Checkbox
Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11523-164008&t=iosNC2AkSTGs5lMh-1
Overview
- The Checkbox component allows users to toggle a binary choice.
- It can display a label with support for multiple languages.
- The component supports default values, read-only mode, and disabled states.
- Data binding and validation options ensure correct handling in forms.
- Events enable dynamic interaction and lifecycle control.
...
Specs
Tokens
| Token | Description |
|---|---|
| displayName | Sets the display name of the component shown in the structure panel. |
| labelTranslations | Sets the label text displayed next to the checkbox, with support for multiple languages. |
| disabled | Determines whether the checkbox is interactive. |
| value | Sets the default checked state of the checkbox. |
| readonly | Controls whether the field is in read-only mode. |
| defaultValue | Sets an initial value for the checkbox when first loaded. |
| saveInLocalStorage | Enables persisting the checkbox state in browser's local storage. |
| dataField | Specifies the form field name where the checkbox value will be stored. |
| controlsRequestType | Specifies how the checkbox data should be included in API requests. |
| validation | Configures validation rules for the checkbox. |
| required | Validation rule: blocks form submission unless the checkbox is checked. |
| requiredTrue | Validation rule: specifically requires the checkbox to be checked (true). |
| events | Configures the events that the component can trigger and respond to. |
| ON_VALUE_CHANGE (Events) | Event triggered when the checkbox is toggled. |
| ON_INIT_BASED_ON_USER_VIEW (Events) | Event triggered when the component is initialized in user view. |
| ON_INIT (Events) | Event triggered when the component is initialized. |
| ON_DESTROY (Events) | Event triggered when the component is removed from the DOM. |
...
- validation – Configures validation rules for the checkbox:
- required – When set to true, form submission is blocked unless the checkbox is checked.
- requiredTrue – Specifically requires the checkbox to be checked (true) for validation to pass, commonly used for terms acceptance.
Links
- Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11523-164008&t=iosNC2AkSTGs5lMh-1
- Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/6-checkbox
Guidelines
Usage
- Use for a binary, user-controlled choice; set a clear label and localize it with
label/labelTranslations. - Initialize a predictable starting state with either
value(current) ordefaultValue(initial before input/reset)—don’t set both to conflicting values. - Use
readonlyto show an uneditable decision; reservedisabledfor when the control is unavailable and non-interactive.
Sizing & Layout
- Add spacing with
paddingClassto keep the control readable and aligned with neighbors.
Data-Driven / Conditional Behavior
- Enforce mandatory confirmations with
validation.requiredTrue(orvalidation.requiredfor general must-check scenarios). - Persist the user’s choice across refreshes or long flows with
saveInLocalStorage; after first load, honor the stored state overdefaultValue. - Bind the value to a meaningful
dataFieldand specify how it is sent withcontrolsRequestType(BODY,PATH,HEADER).
Dos & Don’ts
| Do | Don’t | Article setting(s) |
|---|---|---|
Use validation.requiredTrue for explicit consent requirements. | Rely on helper text alone to imply consent. | validation.requiredTrue |
| Bind the value to a stable field name and choose the right transport. | Leave the field unbound or send it via an unexpected channel. | dataField, controlsRequestType |
| Initialize and reconcile defaults at mount, then keep them stable. | Change defaults mid-session, causing unexpected flips. | defaultValue, ON_INIT |
| Trigger downstream logic directly on user toggle. | Poll the value instead of responding to events. | ON_VALUE_CHANGE |
...
