mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-19 06:21:46 +01:00
2fc938575d
Co-authored-by: Romain Hamel <rom.hml@gmail.com> Co-authored-by: Benjamin Canac <canacb1@gmail.com> Co-authored-by: saveliy <savelii.moshkota@ext.jumingo.com>
309 lines
6.6 KiB
Markdown
309 lines
6.6 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.
|
|
::
|
|
|
|
## Slots
|
|
|
|
### `label`
|
|
|
|
Use the `#label` slot to set the custom content for label.
|
|
|
|
::component-card
|
|
---
|
|
slots:
|
|
label: <UAvatar src="https://avatars.githubusercontent.com/u/739984?v=4" size="3xs" />
|
|
default: <UInput model-value="benjamincanac" placeholder="you@example.com" />
|
|
---
|
|
|
|
#label
|
|
:u-avatar{src="https://avatars.githubusercontent.com/u/739984?v=4" size="3xs" class="mr-2 inline-flex"}
|
|
|
|
#default
|
|
:u-input{model-value="benjamincanac" placeholder="you@example.com"}
|
|
::
|
|
|
|
### `description`
|
|
|
|
Use the `#description` slot to set the custom content for description.
|
|
|
|
::component-card
|
|
---
|
|
slots:
|
|
description: Write only valid email address <UIcon name="i-heroicons-arrow-right-20-solid" />
|
|
default: <UInput model-value="benjamincanac" placeholder="you@example.com" />
|
|
props:
|
|
label: 'Email'
|
|
---
|
|
|
|
#description
|
|
Write only valid email address :u-icon{name="i-heroicons-information-circle" class="align-middle"}
|
|
|
|
#default
|
|
:u-input{model-value="benjamincanac" placeholder="you@example.com"}
|
|
::
|
|
|
|
### `hint`
|
|
|
|
Use the `#hint` slot to set the custom content for hint.
|
|
|
|
::component-card
|
|
---
|
|
slots:
|
|
hint: <UIcon name="i-heroicons-arrow-right-20-solid" />
|
|
default: <UInput model-value="benjamincanac" placeholder="you@example.com" />
|
|
props:
|
|
label: 'Step 1'
|
|
---
|
|
|
|
#hint
|
|
:u-icon{name="i-heroicons-arrow-right-20-solid"}
|
|
|
|
#default
|
|
:u-input{model-value="benjamincanac" placeholder="you@example.com"}
|
|
::
|
|
|
|
### `help`
|
|
|
|
Use the `#help` slot to set the custom content for help.
|
|
|
|
::component-card
|
|
---
|
|
slots:
|
|
help: Here are some examples <UIcon name="i-heroicons-arrow-right-20-solid" />
|
|
default: <UInput model-value="benjamincanac" placeholder="you@example.com" />
|
|
props:
|
|
label: 'Email'
|
|
---
|
|
|
|
#help
|
|
Here are some examples :u-icon{name="i-heroicons-information-circle" class="align-middle"}
|
|
|
|
#default
|
|
:u-input{model-value="benjamincanac" placeholder="you@example.com"}
|
|
::
|
|
|
|
### `error`
|
|
|
|
Use the `#error` slot to set the custom content for error.
|
|
|
|
::component-example
|
|
#default
|
|
:form-group-error-slot-example{class="w-60"}
|
|
|
|
#code
|
|
```vue
|
|
<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 }">
|
|
<UAlert v-if="error" icon="i-heroicons-exclamation-triangle-20-solid" :title="error" color="red" />
|
|
<UAlert v-else icon="i-heroicons-check-circle-20-solid" title="Your email is valid" color="green" />
|
|
</template>
|
|
</UFormGroup>
|
|
</template>
|
|
|
|
<script setup lang="ts">
|
|
const email = ref('')
|
|
</script>
|
|
```
|
|
::
|
|
|
|
## Props
|
|
|
|
:component-props
|
|
|
|
## Preset
|
|
|
|
:component-preset
|