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.

<script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormMessage,
  BrInput,
  BrFlex
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="vertical">
    <BrFlex class="gap-6 w-full flex-col sm:flex-row">
      <BrFormItem name="default" class="flex-1">
        <BrFormLabel>Default State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Normal input" />
        </BrFormControl>
      </BrFormItem>

      <BrFormItem name="success" validation-state="success" success-message="Looks good!" class="flex-1">
        <BrFormLabel>Success State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Valid input" model-value="john_doe" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>

      <BrFormItem name="warning" validation-state="warning" warning-message="Password is weak." class="flex-1">
        <BrFormLabel>Warning State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Warning input" type="password" model-value="123" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>

      <BrFormItem name="error" validation-state="error" error-message="Email is already taken." class="flex-1">
        <BrFormLabel>Error State</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Error input" model-value="test@test" />
        </BrFormControl>
        <BrFormMessage />
      </BrFormItem>
    </BrFlex>
  </BrForm>
</template>

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.

<script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormDescription,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="horizontal" class="max-w-md">
    <BrFormItem name="leftAlign" label-align="left" required>
      <BrFormLabel>Left Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label aligns to the left" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="rightAlign" label-align="right" required>
      <BrFormLabel>Right Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label aligns to the right" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="topAlign" label-align="top" required>
      <BrFormLabel>Top Align</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Label is stacked on top" />
      </BrFormControl>
      <BrFormDescription>Overrides horizontal layout.</BrFormDescription>
    </BrFormItem>
  </BrForm>
</template>

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.

<script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrFormDescription,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="vertical" class="max-w-md">
    <BrFormItem name="customAst" asterisk="(Required)" required spacing="1.5rem">
      <BrFormLabel>Custom Asterisk</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Asterisk is replaced with text" />
      </BrFormControl>
      <BrFormDescription>Spacing is increased via spacing prop.</BrFormDescription>
    </BrFormItem>

    <BrFormItem name="noAst" :asterisk="false" required>
      <BrFormLabel>Hidden Asterisk</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Asterisk is hidden despite being required" />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

Disabled & Readonly

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

<script setup lang="ts">
import {
  BrForm,
  BrFormItem,
  BrFormLabel,
  BrFormControl,
  BrInput
} from '@breezeui/vue'
</script>

<template>
  <BrForm layout="horizontal" class="max-w-md">
    <BrFormItem name="disabled" disabled>
      <BrFormLabel>Disabled</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Cannot interact" />
      </BrFormControl>
    </BrFormItem>

    <BrFormItem name="readonly" readonly>
      <BrFormLabel>Readonly</BrFormLabel>
      <BrFormControl>
        <BrInput model-value="Read-only value" readonly />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

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.

Component 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.

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.

#Validation States

#Label Alignments

#Custom Asterisk & Spacing

#Disabled & Readonly

#Form Item

#Component Features

#API Reference

#BrFormItem

#BrFormLabel

#BrFormControl

#BrFormMessage

#BrFormDescription