docs: add documentation for the experimental Switch component - #5847
Conversation
Document the Switch component, an input field for toggling a single setting on or off, available behind the switchComponent feature flag. The article follows the structure used by the other input field components: a basic example, a Basic Features section built from the shared _input-field-common-features.adoc includes (label, helper, tooltip, ARIA labels), a shared Read-Only & Disabled section, and a Validation section covering the required constraint. Examples are consolidated so each section has a single demo covering its features, in Lit, Flow, and React. The styling page documents the icon variant (Lumo and Aura) along with the Aura-only small and reverse variants, the --vaadin-switch-* style properties, and the shadow parts and state attributes. Also enable switchComponent in the docs application so the examples render, and link the feature flag reference to the new page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-5847.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Other changed files
Built from 141cece |
|
The distinction between a checkbox and a switch should perhaps be made clearer, when to use one over the other. The validation example is problematic for this reason exactly, that a checkbox would be the more appropriate component in that case, where you need to submit the value before it takes effect. Switch is commonly thought to be independent of other components, that its state change takes effect immediately without submitting/saving a form. |
Add a When to Use section near the top of the article, so the distinction from Checkbox is stated where readers look for it rather than only in the Related Components table at the end. It explains that a Switch shows whether a setting is on, that its state is meaningful on its own, and that users expect it to apply immediately, while a Checkbox marks a selection that is normally submitted with a form and supports an indeterminate state. Best Practices gains the note that a switch's change should apply as soon as it's toggled. Recast the validation example accordingly. It previously showed an "I confirm the details are correct" consent bound through Binder with a Submit button, which is the case a Checkbox serves better: the value took effect only on submit. It now demonstrates the required constraint on a setting that a policy keeps on, using the component's own required error message rather than Binder, which also matches how the other input field components document validation. The Switch spec allows both immediate and save-on-submit usage, so deferred usage is still described; only the consent framing is gone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Updated and added dedicated "When to Use" section clarifying this distinction. Also updated validation example. |
a957662 to
c73c93a
Compare
|
Thanks! I might change the validation example slightly still, so that the switch is checked by default, and when you uncheck it, the validation error is shown and says "Required by your workplace security policy" (i.e., change it from a helper text to error-message). And add one sentence to the description before the example that says "Turn off the switch to see the validation message." |
Start the validation example switched on, so the required constraint is satisfied initially and turning the switch off demonstrates the error. The policy text moves from the helper to the error message, where it explains why the setting can't be turned off, and the description tells the reader to turn the switch off to see the message. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Thanks, done. |
2 participants
Added
Switchcomponent documentation and updated feature flag to link to the new page.Note: screenshot for the components page is currently missing, I will create one later.