Display a label and additional informations around a form element.
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>
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>
Use the description
prop to display a description below the label.
<template>
<UFormGroup label="Email" description="We'll only use this for spam.">
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
</UFormGroup>
</template>
Use the hint
prop to display a hint above the form element.
<template>
<UFormGroup label="Email" hint="Optional">
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
</UFormGroup>
</template>
Use the help
prop to display a help message below the form element.
<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>
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.
<template>
<UFormGroup 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 thecolor
prop of the form element tored
.
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.
Use the size
prop to change the size of the label and the form element.
<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.
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>
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.
<template>
<UFormGroup label="Email">
<template #description>
Write only valid email address
<UIcon name="i-heroicons-information-circle" />
</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.
<template>
<UFormGroup label="Email">
<template #help>
Here are some examples
<UIcon name="i-heroicons-information-circle" />
</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.
<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>
name
: stringsize
: FormGroupSize (md, 2xs, xs, sm, lg, xl)label
: stringui
: Configuration object for stylingerror
: string | booleanhelp
: stringdescription
: stringhint
: stringrequired
: boolean (default: false)eagerValidation
: boolean (default: false){
"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"
}
}