mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-17 05:28:09 +01:00
200 lines
4.0 KiB
Markdown
200 lines
4.0 KiB
Markdown
---
|
|
title: FormGroup
|
|
description: Display a label and additional informations around a form element.
|
|
links:
|
|
- label: GitHub
|
|
icon: i-simple-icons-github
|
|
to: https://github.com/nuxt/ui/blob/dev/src/runtime/components/forms/FormGroup.vue
|
|
---
|
|
|
|
|
|
## Usage
|
|
|
|
Use the FormGroup component around an [Input](/forms/input), [Textarea](/forms/textarea), [Select](/forms/select) or a [SelectMenu](/forms/select-menu) with the `name` prop to automatically associate a `<label>` element with the form element.
|
|
|
|
::component-card
|
|
---
|
|
props:
|
|
label: 'Email'
|
|
name: 'email'
|
|
code: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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
|
|
```vue
|
|
<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: >-
|
|
|
|
<UInput placeholder="you@example.com" />
|
|
---
|
|
|
|
#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: >-
|
|
|
|
<UInput placeholder="you@example.com" icon="i-heroicons-envelope" />
|
|
---
|
|
|
|
#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
|