All examples demonstrate Salt form controls inside the form field, including Input, Checkbox and RadioButton. These components are available as part of the Salt component library in addition to FormField.

A form field is a wrapper for UI controls typically found in a form (for example, Input, Combobox or RadioButton). Form fields make these controls accessible by providing them with a visible label, validation control, states and descriptive text elements.

You can disable a form field via the prop disabled.

• Apply the prop to the field, not the control it contains, for expected results.
• You'd typically disable a form field if the context or required permissions prevent the user from interacting with a field.
• Text contrast isn't WCAG AA compliant; an editable field is only in the disabled state if the field isn't relevant at the time.

Form Field can display helper text using the FormFieldHelperText component:

• Use helper text to provide additional guidance to users, such as an instruction (when it’s not obvious what action the user must take) or if you need to show an example of acceptable formats to increase the likelihood of successful entry.
• Keep your form label short by moving guidance to the helper text.

Display the helper text in a tooltip when you're low on screen real estate.

Form fields provides a visible label which you should use to describe the form control in the field. The label is above the form control by default. Display the label via the FormFieldLabel component:

• Users should be able to easily scan the label, which should be no more than three words long.
• Use the label to describe the information or data the field is collecting (e.g., Name, Location, Currency).
• Use FormFieldHelperText to provide additional information and context to help the user complete the field.

You can position the form field label to the left of the form control via the prop labelPlacement:

• Place your label to the left of the control if your application has limitations in vertical real estate or you have a very data-heavy, dense form that should show as many fields visible as possible without scrolling.

You can style form field labels with a different intent by setting the intent prop. Use “sentence” intent for sentences and questions. See more about displaying labels.

You can display multiple controls within a single form field. Wrap the controls in StackLayout for the correct styling.

If a field is necessary, you can mark it with a "Required”, “Optional” or “*” indicator using the necessity prop.

You can set a form field as read-only via the prop readOnly:

• Apply the prop to the field, not the control it contains, for expected results.
• Set the field to read-only if you’re displaying predefined, noneditable values, e.g., entry populated and fixed by template selection.
• Test must adhere to WCAG AA text contrast for legibility; read-only field content is always relevant to the form, but users cannot change it.

Form fields can show validation states (warning, success, error) with the prop validationStatus:

• Apply the prop to the field, not the control it contains, for expected results.
• Use the error state to alert the user of a critical issue related to the field entry. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve it.
• Display the warning state when you need to alert the user of a potential issue that won’t prevent them from continuing with the task, but may cause errors if they don't address it.

Form fields can wrap any Salt UI control typically found in a form, such as Input, Checkbox and ComboBox components. This example shows radio button, checkbox and switch controls used within a form field.

• Form fields don't have primary and secondary variants. Any variants apply to the field controls contained within the form field, and you can display them via the component's variant prop if supported.

Wrap multiple form fields in StackLayout to form a group:

• Use the same label placement on each field.
• Spread grouped props on the form fields to reduce code repetition.
• Set role="group" or as="fieldset" on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling.

This example shows a group with the fields labelPlacement props set to "left":

Wrap multiple form fields in StackLayout to form a group.

• Use the same label placement on each field.
• Spread grouped props on the Form Fields to reduce code repetition.
• Set role="group" or as="fieldset" on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling.

This example shows a group with the fields labelPlacement props set to "top".

Wrap multiple form fields in StackLayout to form a group.

• Use the same label placement on each field.
• Spread grouped props on the form fields to reduce code repetition.
• Set role="group" or as="fieldset" on the layout component for accessibility. If using a fieldset, you should override browser fieldset styling.

This example shows a group with the fields labelPlacement props set to "right".

Use multiple stack layouts inside a group to create a multiple column layout.

Use GridLayout within a group to create multiple columns where empty slots may be present.

Grouped form fields should all have the same variant. Set the same variant prop on each field. To avoid code repetition, spread the props onto the fields.