BreezeUI
  • English

    • Basic Form (Horizontal Layout)

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

    <script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'
import { 
  BrForm, BrFormItem, BrFormLabel, BrFormControl, BrFormMessage, BrFormDescription,
  BrInput, BrButton 
} from '@breezeui/vue'

const formSchema = toTypedSchema(z.object({
  username: z.string().min(2, 'Username requires at least 2 characters'),
}))

const onSubmit = (values: any) => {
  console.log('Submitted data:', values)
}
</script>

<template>
  <BrForm layout="horizontal" :validation-schema="formSchema" @submit="onSubmit">
    <BrFormItem name="username" required>
      <BrFormLabel>Username</BrFormLabel>
      <BrFormControl>
        <BrInput placeholder="Please enter username" />
      </BrFormControl>
      <BrFormDescription>Unique identifier used to log into the system</BrFormDescription>
      <BrFormMessage />
    </BrFormItem>

    <BrFormItem>
      <div class="col-start-2 mt-4">
        <BrButton type="submit">Submit</BrButton>
      </div>
    </BrFormItem>
  </BrForm>
</template>

    Form with Complex Validation Rules

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

    <script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'
import { 
  BrForm, BrFormItem, BrFormLabel, BrFormControl, BrFormMessage,
  BrInput, BrButton 
} from '@breezeui/vue'

const formSchema = toTypedSchema(z.object({
  password: z.string().min(8, 'Password length cannot be less than 8 characters'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords do not match",
  path: ["confirmPassword"],
}))

const onSubmit = (values: any) => {
  console.log(values)
}
</script>

<template>
  <BrForm layout="vertical" :validation-schema="formSchema" @submit="onSubmit">
    <BrFormItem name="password" required>
      <BrFormLabel>Password</BrFormLabel>
      <BrFormControl>
        <BrInput type="password" placeholder="Please enter password" />
      </BrFormControl>
      <BrFormMessage />
    </BrFormItem>

    <BrFormItem name="confirmPassword" required>
      <BrFormLabel>Confirm Password</BrFormLabel>
      <BrFormControl>
        <BrInput type="password" placeholder="Please enter password again" />
      </BrFormControl>
      <BrFormMessage />
    </BrFormItem>

    <BrButton type="submit" class="mt-4">Register</BrButton>
  </BrForm>
</template>

    Grid Layout Form

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

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

const onSubmit = (values: any) => {
  console.log(values)
}
</script>

<template>
  <BrForm layout="vertical" @submit="onSubmit">
    <BrGrid :cols="2" gap="4">
      <BrGridItem>
        <BrFormItem name="firstName">
          <BrFormLabel>First Name</BrFormLabel>
          <BrFormControl>
            <BrInput placeholder="First Name" />
          </BrFormControl>
          <BrFormMessage />
        </BrFormItem>
      </BrGridItem>
      
      <BrGridItem>
        <BrFormItem name="lastName">
          <BrFormLabel>Last Name</BrFormLabel>
          <BrFormControl>
            <BrInput placeholder="Last Name" />
          </BrFormControl>
          <BrFormMessage />
        </BrFormItem>
      </BrGridItem>
    </BrGrid>

    <BrButton type="submit" class="mt-4">Submit</BrButton>
  </BrForm>
</template>

    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:

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

    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.

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

    API Reference

    BrForm

    PropertyTypeDefaultDescription
    layout'vertical' | 'horizontal' | 'inline''vertical'Form layout type
    size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl''md'Global size of form controls
    hideRequiredAsteriskbooleanfalseWhether to hide the red asterisk for required fields
    showMessagebooleantrueWhether to globally show error messages
    keepValuesbooleanfalseWhether to keep form values when unmounted

    BrFormItem

    PropertyTypeDefaultDescription
    namestring-Field name of the form item, used for validation and data binding
    requiredbooleanfalseWhether it is required (also inferred automatically from validation rules)
    rulesany-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.