FormField

GitHub
提供验证和错误处理的表单元素包装器。

用法

使用FormField包装任何表单组件。在Form中使用，它提供验证和错误处理。

Label

使用label属性为表单控件设置标签。

<template>
  <UFormField label="Email">
    <UInput placeholder="Enter your email" />
  </UFormField>
</template>
标签for属性和表单控件与唯一的id相关联（如果未提供）。

当使用required属性时，标签旁边会添加一个星号。

<template>
  <UFormField label="Email" required>
    <UInput placeholder="Enter your email" />
  </UFormField>
</template>

说明

使用description prop在标签下方提供其他信息。

We'll never share your email with anyone else.

<template>
  <UFormField label="Email" description="We'll never share your email with anyone else.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

Hint

使用hint属性在标签旁边显示提示消息。

Optional
<template>
  <UFormField label="Email" hint="Optional">
    <UInput placeholder="Enter your email" />
  </UFormField>
</template>

帮助

使用help prop在表单控件下显示帮助消息。当与error prop一起使用时，error prop优先。

Please enter a valid email address.
<template>
  <UFormField label="Email" help="Please enter a valid email address.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

Error

使用error prop在表单控件下显示错误消息。当与help prop一起使用时，error prop优先。

当在Form中使用时，发生验证错误时会自动设置此值。

Please enter a valid email address.
<template>
  <UFormField label="Email" error="Please enter a valid email address.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
这将表单控件上的color设置为error。您可以在app.config.ts中全局更改它。

错误模式

使用error-pattern属性来匹配正则表达式中的表单错误。这对于带有数组值的组件（如InputTags）尤其重要，其中错误在其名称中包含数组索引（例如tags.0）。

查看在Form中使用error-pattern的示例。

Size

使用size属性更改FormField的大小，size将被代理到表单控件。

Optional

We'll never share your email with anyone else.

Please enter a valid email address.
<template>
  <UFormField
    label="Email"
    description="We'll never share your email with anyone else."
    hint="Optional"
    help="Please enter a valid email address."
    size="xl"
  >
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

方向：badge{label="4.3+" class="align-text-top"}

使用orientation属性将FormField.xml的布局更改为vertical。

Please enter a valid email address.
<template>
  <UFormField
    orientation="horizontal"
    label="Email"
    help="Please enter a valid email address."
    class="w-72"
  >
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

API

Props

Prop Default Type
as
'div'
any

The element or component this component should render as.

name
string

The name of the FormField. Also used to match form errors.

errorPattern
RegExp

A regular expression to match form error names. Useful for components with array values such as InputTags, where errors include array indices in their name (e.g. tags.0).

label
string
description
string
help
string
error
undefined
string | false | true
hint
string
size
'md'
"md" | "xs" | "sm" | "lg" | "xl"
required
boolean
eagerValidation
boolean

If true, validation on input will be active immediately instead of waiting for a blur event.

validateOnInputDelay
`300`
number

Delay in milliseconds before validating the form on input events.

orientation
'vertical'
"vertical" | "horizontal"

The orientation of the form field.

ui
{ root?: SlotClass; wrapper?: SlotClass; labelWrapper?: SlotClass; label?: SlotClass; container?: SlotClass; description?: SlotClass; error?: SlotClass; hint?: SlotClass; help?: SlotClass; }

Slots

Slot Type
label
{ label: string | undefined; }
hint
{ hint: string | undefined; }
description
{ description: string | undefined; }
help
{ help: string | undefined; }
error
{ error: string | true | undefined; }
default
{ error: string | true | undefined; }

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    formField: {
      slots: {
        root: '',
        wrapper: '',
        labelWrapper: 'flex content-center items-center justify-between gap-1',
        label: 'block font-medium text-default',
        container: 'relative',
        description: 'text-muted',
        error: 'mt-2 text-error',
        hint: 'text-muted',
        help: 'mt-2 text-muted'
      },
      variants: {
        size: {
          xs: {
            root: 'text-xs'
          },
          sm: {
            root: 'text-xs'
          },
          md: {
            root: 'text-sm'
          },
          lg: {
            root: 'text-sm'
          },
          xl: {
            root: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        orientation: {
          vertical: {
            container: 'mt-1'
          },
          horizontal: {
            root: 'flex justify-between place-items-baseline gap-2'
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        formField: {
          slots: {
            root: '',
            wrapper: '',
            labelWrapper: 'flex content-center items-center justify-between gap-1',
            label: 'block font-medium text-default',
            container: 'relative',
            description: 'text-muted',
            error: 'mt-2 text-error',
            hint: 'text-muted',
            help: 'mt-2 text-muted'
          },
          variants: {
            size: {
              xs: {
                root: 'text-xs'
              },
              sm: {
                root: 'text-xs'
              },
              md: {
                root: 'text-sm'
              },
              lg: {
                root: 'text-sm'
              },
              xl: {
                root: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            },
            orientation: {
              vertical: {
                container: 'mt-1'
              },
              horizontal: {
                root: 'flex justify-between place-items-baseline gap-2'
              }
            }
          },
          defaultVariants: {
            size: 'md'
          }
        }
      }
    })
  ]
})

Changelog

No recent changes

Form

A form component with built-in validation and submission handling.

Input

An input element to enter text.