Das Formfeld

Ein Wrapper für Formularelemente, der Validierung und Fehlerbehandlung bietet.

Bearbeiten

Wickeln Sie eine beliebige Formularkomponente mit einem FormField ein. Wird in einem Form verwendet, bietet es Validierung und Fehlerbehandlung.

Label

Verwenden Sie die prop label, um das Label für das Formularsteuerelement festzulegen.

label

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

Das Attribut label for und das Formular-Steuerelement sind mit einem eindeutigen id verknüpft, falls nicht angegeben.

Wenn Sie die required-Prop verwenden, wird neben dem Etikett ein Sternchen hinzugefügt.

required

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

xph031Beschreibung

Verwenden Sie die description-Prop, um zusätzliche Informationen unterhalb des Etiketts anzugeben.

description

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 (englisch)

Verwenden Sie die hint-Prop, um eine Hinweismeldung neben dem Etikett anzuzeigen.

hint

EmailOptional

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

Help Hilfe

Verwenden Sie die help-prop, um eine Hilfemeldung unterhalb des Formular-Steuerelements anzuzeigen. Wenn sie zusammen mit der error-prop verwendet wird, hat die error-prop Vorrang.

help

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>

Fehler

Verwenden Sie die error-prop, um eine Fehlermeldung unterhalb des Formular-Steuerelements anzuzeigen. Wenn sie zusammen mit der help-prop verwendet wird, hat die error-prop Vorrang.

Bei Verwendung in einem Form wird dies automatisch gesetzt, wenn ein Validierungsfehler auftritt.

error

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>

Dies setzt den Wert color auf error im Formular-Steuerelement. Sie können ihn global in Ihrem app.config.ts ändern.

Error Pattern (Fehlerbild)

Dies ist besonders relevant für Komponenten mit Array-Werten wie InputTags, bei denen Fehler Array-Indizes in ihrem Namen enthalten (z. B. tags.0).

Hier sehen Sie ein Beispiel für die Verwendung von error-pattern in einem Formular.

Size ist

Verwenden Sie die size-prop, um die Größe des FormField zu ändern, die size wird an das Formularsteuerelement proxiert.

size

EmailOptional

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>

Orientierung: badgexx128x

Verwenden Sie die orientation-prop, um das Layout der FormField. Defaults auf vertical zu ändern.

orientation

help

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 Bearbeiten

Props Bearbeiten

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 (englisch)

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 Bearbeiten

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 (englisch)

No recent changes

Form

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

Input

An input element to enter text.