component-guidance-forms

Component Guidance - Forms & Inputs

Form controls and input components for data entry.

When to Use This Skill

Use this skill when:

• The user asks "Should I use [component] for [use case]?"
• The user needs to choose between similar components
• The user asks about component best practices
• The user wants to know when NOT to use a component

This skill covers: Checkbox, Combobox Input, Date Picker, Fieldset, File Uploader, Form Grid, Form Group, Form Header, Form Item, Form Label, Form Message, Input, Input Group, Multi ComboBox, Multi Input, Radio, Select, Slider, Step Input, Switch, Textarea, Time, Time Picker, Token, Tokenizer, Upload Collection

Checkbox

Description: A checkbox lets users set a binary value (true/false). When selected, it toggles between checked (state applies), unchecked (state doesn't apply), and optionally tri-state/indeterminate (mixed selection of dependent fields). All options are visible, and users can make one or more independent selections.

When to use:

• Only one option can be selected or deselected (e.g., accept terms of use) when meaning is obvious
• A group or list of options can be selected independently of each other
• Options are displayed immediately without user interaction
• Intermediate selection state (tri-state) is required when multiple sub-options are grouped under a parent option

When to avoid:

• ❌ User needs to choose multiple options from a large list → Use Combo Box Input instead
• ❌ User can choose only one option from a list → Use Radio Buttons, Select, or List instead
• ❌ User needs to perform instantaneous actions without reviewing or confirming → Use Switch instead
• ❌ Not enough space available on screen → Use Combo Box instead

Best practices:

• ✅ Checked state means the described state applies or item is chosen
• ✅ Unchecked state means the described state doesn't apply
• ✅ Tri-state/indeterminate indicates neither checked nor unchecked (set via JavaScript indeterminate property)
• ✅ Use tri-state to represent mixed selection when some (but not all) dependent fields are selected
• ✅ All options visible without user interaction
• ⚠️ Tri-state is visual only and cannot be achieved by direct user interaction
• ⚠️ Use for independent selections where multiple options can be selected simultaneously