forms

FormGroup

GitHub

Display a label and additional informations around a form element.

Usage

Use the FormGroup component around an Input, Textarea, Select or a SelectMenu with the name prop to automatically associate a <label> element with the form element.

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

Required

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

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

Description

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

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

Hint

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

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

Help

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

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

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.

<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'" />
  </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.

<UFormGroup label="Email" error>
<UInput placeholder="you@example.com" /></UFormGroup>
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.

<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>
This will only work with form elements that support the size prop.

Props

name
string

null

size
string

null

ui
any

{}

error
string | boolean

null

help
string

null

label
string

null

description
string

null

hint
string

null

required
boolean

false

Preset

appConfig.ui.formGroup
{
  "wrapper": "",
  "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"
}

Range

Display a range field

Table

Display data in a table.