Form

An enterprise-level form component with global theme configuration via BrConfigProvider, supporting validation, layout, linkage, and accessibility. Built on top of vee-validate and @vee-validate/zod to provide an ultimate type-safe validation experience.

Features

• 🔒 Type Safe: Schema validation based on Zod
• 🎨 Theming: Manage form colors, sizes, and spacing centrally via BrConfigProvider
• 📐 Multiple Layouts: Supports vertical, horizontal, inline, and grid layouts
• ♿️ Accessibility: Automatically generates aria-describedby and aria-invalid attributes
• ⚡ State Feedback: Automatically handles error messages and input highlights

---

Basic Form (Horizontal Layout)

Use layout="horizontal" to quickly build a common enterprise horizontal form.

Username*

Unique identifier used to log into the system

Example

Form with Complex Validation Rules

Combine vee-validate and zod to easily implement async validation and multi-field validation.

Password*

Confirm Password*

Example

Grid Layout Form

In complex form scenarios, combine with BrGrid to implement multi-column responsive layouts.

First Name

Last Name

Example

Theme Customization

BrForm is fully integrated with the BrConfigProvider design token system. You can customize it through global configuration or Tailwind classes.

Global Configuration (BrConfigProvider)

Globally modify form theme colors and validation colors via BrConfigProvider:

<script setup>
import { BrConfigProvider, BrForm, BrFormItem, BrFormLabel, BrFormControl, BrInput } from '@breezeui/vue'

const theme = {
  primary: '#8b5cf6',   // Border color for focus state
  error: '#ef4444',     // Text and border color for validation failure
  radius: 0.5,          // Input border radius
}
</script>

<template>
  <BrConfigProvider :theme="theme">
    <BrForm>
      <BrFormItem name="demo" required>
        <BrFormLabel>Global Theme Form</BrFormLabel>
        <BrFormControl>
          <BrInput placeholder="Custom colors will be shown on focus or error" />
        </BrFormControl>
      </BrFormItem>
    </BrForm>
  </BrConfigProvider>
</template>

Local Style Override (TailwindCSS)

You can easily override the default styles of a single form by passing class or local CSS variables:

<template>
  <BrForm 
    layout="horizontal" 
    class="[--br-form-label-width:150px]" <!-- Custom label width for horizontal form -->
  >
    <BrFormItem name="email">
      <BrFormLabel class="text-blue-500 text-base">Custom Label</BrFormLabel>
      <BrFormControl>
        <BrInput class="bg-gray-50 border-gray-300" />
      </BrFormControl>
    </BrFormItem>
  </BrForm>
</template>

---

API Reference

BrForm

Property	Type	Default	Description
layout	'vertical' | 'horizontal' | 'inline'	'vertical'	Form layout type
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'	Global size of form controls
hideRequiredAsterisk	boolean	false	Whether to hide the red asterisk for required fields
showMessage	boolean	true	Whether to globally show error messages
keepValues	boolean	false	Whether to keep form values when unmounted

BrFormItem

Property	Type	Default	Description
name	string	-	Field name of the form item, used for validation and data binding
required	boolean	false	Whether it is required (also inferred automatically from validation rules)
rules	any	-	Native validation rules for vee-validate

BrFormLabel

Encapsulated based on BrLabel, automatically reads id and required state from FormItem 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 FormControl.