Components

FormGroup

Display a label and additional informations around a form element.

Usage

Use the FormGroup component around an Input, Textarea, Select or a SelectMenu with a label. The <label> will automatically be associated with the form element so it gets focused on click.

<template>
  <UFormGroup label="Email">
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

Required

Use the required prop to indicate that the form element is required.

<template>
  <UFormGroup label="Email" required>
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

Description

Use the description prop to display a description below the label.

We'll only use this for spam.

<template>
  <UFormGroup label="Email" description="We'll only use this for spam.">
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

Hint

Use the hint prop to display a hint above the form element.

Optional
<template>
  <UFormGroup label="Email" hint="Optional">
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

Help

Use the help prop to display an help message below the form element.

We will never share your email with anyone else.

<template>
  <UFormGroup
    label="Email"
    help="We will never share your email with anyone else."
  >
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

Error

Use the error prop to display an error message below the form element.

When used together with the help prop, the error prop will take precedence.

You must enter an email

<template>
  <UFormGroup v-slot="{ error }" label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
    <UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error ? 'i-heroicons-exclamation-triangle-20-solid' : undefined" />
  </UFormGroup>
</template>

<script setup lang="ts">
const email = ref('')
</script>
The error prop will automatically set the color prop of the form element to red.

You can also use the error prop as a boolean to mark the form element as invalid.

<template>
  <UFormGroup label="Email" error>
    <UInput placeholder="you@example.com" />
  </UFormGroup>
</template>
Learn more about form validation in the Form component.

Size

Use the size prop to change the size of the label and the form element.

Optional

We'll only use this for spam.

We will never share your email with anyone else.

<template>
  <UFormGroup
    size="xl"
    label="Email"
    hint="Optional"
    description="We'll only use this for spam."
    help="We will never share your email with anyone else."
  >
    <UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>
This will only work with form elements that support the size prop.

Eager Validation

By default, validation is only triggered after the initial blur event. This is to prevent the form from being validated as the user is typing. You can override this behavior by setting the eager-validation prop to true

<template>
  <UForm :schema="schema" :state="state" class="space-y-4">
    <UFormGroup label="Username" name="username" eager-validation>
      <UInput v-model="state.username" placeholder="Choose Username" />
    </UFormGroup>
  </UForm>
</template>

<script setup lang="ts">
import { z } from 'zod'

const schema = z.object({
  username: z.string().min(10, 'Must be at least 10 characters')
})

const state = reactive({
  username: undefined
})
</script>

Slots

label

Use the #label slot to set the custom content for label.

<template>
  <UFormGroup>
    <template #label>
      <UAvatar
        src="https://avatars.githubusercontent.com/u/739984?v=4"
        size="3xs"
      />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="you@example.com" />
    </template>
  </UFormGroup>
</template>

description

Use the #description slot to set the custom content for description.

Write only valid email address

<template>
  <UFormGroup label="Email">
    <template #description>
      Write only valid email address
      <UIcon name="i-heroicons-arrow-right-20-solid" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="you@example.com" />
    </template>
  </UFormGroup>
</template>

hint

Use the #hint slot to set the custom content for hint.

<template>
  <UFormGroup label="Step 1">
    <template #hint>
      <UIcon name="i-heroicons-arrow-right-20-solid" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="you@example.com" />
    </template>
  </UFormGroup>
</template>

help

Use the #help slot to set the custom content for help.

Here are some examples

<template>
  <UFormGroup label="Email">
    <template #help>
      Here are some examples <UIcon name="i-heroicons-arrow-right-20-solid" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="you@example.com" />
    </template>
  </UFormGroup>
</template>

error

Use the #error slot to set the custom content for error.

You must enter an email

<template>
  <UFormGroup label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
    <template #default="{ error }">
      <UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error ? 'i-heroicons-exclamation-triangle-20-solid' : undefined" />
    </template>

    <template #error="{ error }">
      <span :class="[error ? 'text-red-500 dark:text-red-400' : 'text-primary-500 dark:text-primary-400']">
        {{ error ? error : 'Your email is valid' }}
      </span>
    </template>
  </UFormGroup>
</template>

<script setup lang="ts">
const email = ref('')
</script>

Props

name
string
null
ui
{}
{}
label
string
null
size
FormGroupSize
null
"md""2xs""xs""sm""lg""xl"
error
string | boolean
null
help
string
null
description
string
null
hint
string
null
required
boolean
false
eagerValidation
boolean
false

Config

{
  wrapper: '',
  inner: '',
  label: {
    wrapper: 'flex content-center items-center justify-between',
    base: 'block font-medium text-gray-700 dark:text-gray-200',
    required: "after:content-['*'] after:ms-0.5 after:text-red-500 dark:after:text-red-400",
  },
  size: {
    '2xs': 'text-xs',
    xs: 'text-xs',
    sm: 'text-sm',
    md: 'text-sm',
    lg: 'text-sm',
    xl: 'text-base',
  },
  container: 'mt-1 relative',
  description: 'text-gray-500 dark:text-gray-400',
  hint: 'text-gray-500 dark:text-gray-400',
  help: 'mt-2 text-gray-500 dark:text-gray-400',
  error: 'mt-2 text-red-500 dark:text-red-400',
  default: {
    size: 'sm',
  },
}