FormField

Um wrapper para elementos de formulário que fornece validação e tratamento de erros.

Uso

Envolva qualquer componente de formulário com um FormField. Usado em um Form, ele oferece validação e tratamento de erros.

Label

Use a prop label para definir o rótulo do controle de formulário.

label

<template>
  <NFormField label="Email">
    <NInput placeholder="Enter your email" />
  </NFormField>
</template>

O atributo for do rótulo e o controle de formulário são associados por um id único, se não for fornecido.

Ao usar a prop required, um asterisco é adicionado ao lado do rótulo.

required

<template>
  <NFormField label="Email" required>
    <NInput placeholder="Enter your email" />
  </NFormField>
</template>

Descrição

Use a prop description para fornecer informações adicionais abaixo do rótulo.

description

We'll never share your email with anyone else.

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

Dica

Use a prop hint para exibir uma mensagem de dica ao lado do rótulo.

hint

EmailOptional

<template>
  <NFormField label="Email" hint="Optional">
    <NInput placeholder="Enter your email" />
  </NFormField>
</template>

Ajuda

Use a prop help para exibir uma mensagem de ajuda abaixo do controle de formulário. Quando usada junto com a prop error, a prop error tem precedência.

help

Please enter a valid email address.

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

Erro

Use a prop error para exibir uma mensagem de erro abaixo do controle de formulário. Quando usada junto com a prop help, a prop error tem precedência.

Quando usada dentro de um Form, isso é definido automaticamente quando ocorre um erro de validação.

error

Please enter a valid email address.

<template>
  <NFormField label="Email" error="Please enter a valid email address.">
    <NInput placeholder="Enter your email" class="w-full" />
  </NFormField>
</template>

Isso define a color como error no controle de formulário. Você pode alterar isso globalmente no seu app.config.ts.

Use a prop error-pattern para associar os erros do formulário a uma expressão regular. Isso é especialmente relevante para componentes com valores de array, como o InputTags, em que os erros incluem os índices do array no nome (ex.: tags.0).

Veja um exemplo de uso de error-pattern dentro de um Form.

Tamanho

Use a prop size para alterar o tamanho do FormField; o size é repassado ao controle de formulário.

size

EmailOptional

We'll never share your email with anyone else.

Please enter a valid email address.

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

Orientação 4.3+

Use a prop orientation para alterar o layout do FormField. O padrão é vertical.

orientation

help

Please enter a valid email address.

<template>
  <NFormField
    orientation="horizontal"
    label="Email"
    help="Please enter a valid email address."
    class="w-72"
  >
    <NInput placeholder="Enter your email" class="w-full" />
  </NFormField>
</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; }`

Tema

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',
        orientation: 'vertical'
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/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',
            orientation: 'vertical'
          }
        }
      }
    })
  ]
})

Changelog

No recent changes

Form

Um componente de formulário com validação e tratamento de envio embutidos.

Input

Um elemento de input para digitar texto.