ui/docs/content/3.forms/9.form-group.md

title, description, links

title	description	links
FormGroup	Display a label and additional informations around a form element.	label icon to GitHub i-simple-icons-github https://github.com/nuxt/ui/blob/dev/src/runtime/components/forms/FormGroup.vue

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.

::component-card

props: label: 'Email' name: 'email' code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

Required

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

::component-card

baseProps: name: 'group-required' props: label: 'Email' required: true code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

Description

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

::component-card

baseProps: name: 'group-description' props: label: 'Email' description: "We'll only use this for spam." code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

Hint

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

::component-card

baseProps: name: 'group-hint' props: label: 'Email' hint: 'Optional' code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

Help

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

::component-card

baseProps: name: 'group-help' props: label: 'Email' help: 'We will never share your email with anyone else.' code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

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.

::component-example #default :form-group-error-example

#code

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

::

::callout{icon="i-heroicons-light-bulb"} 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.

::component-card

baseProps: name: 'group-error' props: label: 'Email' error: true excludedProps:

• ui
• error
• label code: >-

---

#default :u-input{model-value="benjamincanac" placeholder="you@example.com"} ::

::callout{icon="i-heroicons-light-bulb" to="/forms/form"} 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.

::component-card

props: size: 'xl' label: 'Email' hint: 'Optional' description: "We'll only use this for spam." help: 'We will never share your email with anyone else.' excludedProps:

• label
• hint
• description
• help code: >-

---

#default :u-input{placeholder="you@example.com" icon="i-heroicons-envelope"} ::

::callout{icon="i-heroicons-exclamation-triangle"} This will only work with form elements that support the size prop. ::

Props

:component-props

Preset

:component-preset