Form Item

The BrFormItem component is used to encapsulate a single form field, managing its label, control, description, and validation messages. It seamlessly integrates with BrForm and provides extensive customization for individual field layouts and states.

Features

• 🚦 Validation States: Built-in support for success, warning, and error states with custom messages
• 📐 Flexible Layout: Individual label alignment (left, right, top) overriding the global form layout
• ✨ Custom Indicators: Fully customizable required field asterisks or text
• ♿️ Accessibility: Automatically links labels, descriptions, and error messages to the form control

---

Validation States

You can explicitly set the validationState of a BrFormItem to success, warning, or error. Combine this with successMessage, warningMessage, or errorMessage to display the appropriate feedback.

Default State

Success State

Looks good!

Warning State

Password is weak.

Error State

Email is already taken.

Example

Label Alignments

When using a horizontal form layout, you can override the alignment of individual labels using the labelAlign prop. Setting it to top will stack the label above the control, ignoring the horizontal layout for that specific item.

Left Align*

Right Align*

Top Align*

Overrides horizontal layout.

Example

Custom Asterisk & Spacing

Customize the required indicator using the asterisk prop. You can pass a string to replace the default red asterisk, or pass false to hide it completely even if the field is required. The spacing prop allows you to adjust the gap between the form item elements.

Custom Asterisk*

Spacing is increased via spacing prop.

Hidden Asterisk*

Example

Disabled & Readonly

Set disabled or readonly states on the BrFormItem to automatically apply these states to the inner control and adjust the visual appearance.

Disabled

Readonly

Example

---

API Reference

BrFormItem

Property	Type	Default	Description
name	string	-	Field name of the form item, used for validation and data binding
required	boolean	false	Whether the field is required. Also inferred automatically from validation rules
rules	any	-	Native validation rules for vee-validate
validationState	'success' | 'warning' | 'error' | 'default'	'default'	Explicit validation state
successMessage	string	-	Message to display when state is success
warningMessage	string	-	Message to display when state is warning
errorMessage	string	-	Message to display when state is error
labelAlign	'left' | 'right' | 'top'	-	Alignment of the label. Overrides form layout if set
asterisk	boolean | string	true	Custom required indicator. Set to false to hide
spacing	string	-	Custom spacing between form item elements (e.g., '1rem')
disabled	boolean	false	Whether the form item is disabled
readonly	boolean	false	Whether the form item is readonly

BrFormLabel

Encapsulated based on BrLabel, automatically reads id and required state from BrFormItem context. Supports inheriting all native <label> attributes.

BrFormControl

Passes id, aria-invalid, aria-describedby, size, error, and form event bindings (v-model) from context to child components via Slot. Only one child element is allowed inside.

BrFormMessage

Automatically reads and displays the validation error message of the current form field. Supports overriding the display content using the default slot.

BrFormDescription

Provides helpful text for the form item, automatically associated with the aria-describedby of BrFormControl.