Field
Labels, Beschreibungen und Fehler, mit ihrem Steuerelement verbunden, mit Validierungszuständen und Layouts für Formulare.
pnpm dlx shadcn@latest add https://hextaui.com/r/field.jsonFügt die Komponente, die HextaUI-Theme-Tokens und alle HextaUI-Komponenten hinzu, von denen sie abhängt.
Füge die Theme-Tokens zu deinem globalen CSS hinzu, falls du das noch nicht getan hast.
Installiere die Abhängigkeiten.
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cnKopiere den folgenden Code und füge ihn in dein Projekt ein.
components/ui/field.tsx components/ui/input.tsx components/ui/number-flow.tsx components/ui/separator.tsx lib/motion.ts Passe die Importpfade an dein Projekt-Setup an.
Setze ein beliebiges HextaUI-Steuerelement in ein <Field />, und es wird automatisch beschriftet, beschrieben und validiert. id, htmlFor oder aria-describedby musst du nicht von Hand verdrahten.
Ein Steuerelement mit Label, Hilfetext und Validierung.
Ein Switch oder eine Checkbox mit ihrem Text daneben.
Ein Label, das ein ganzes Feld umschließt, sodass die Karte das Klickziel ist.
Zusammengehörige Felder, gleichmäßig verteilt.
Eine betitelte Gruppe von Feldern oder eine Radio- oder Checkbox-Gruppe mit einem Eintrag pro Option.
Input
Ein Label, ein Steuerelement und eine Beschreibung. Ein Klick auf das Label fokussiert das Input, und Screenreader lesen die Beschreibung nach dem Label vor.
Validierung
Native Einschränkungen wie required und minLength werden beim Verlassen des Felds geprüft. Gib jedem <FieldError /> ein match, um die Meldung pro Problem zu formulieren. Ein leeres Pflichtfeld wird erst markiert, nachdem es bearbeitet wurde, sodass das Vorbeitabben nicht anschreit.
Eigene Validierung
Übergib validate, um beliebige Dinge zu prüfen, auch asynchrone Abfragen. Gib eine Meldung zurück, um zu scheitern, oder nichts, um zu bestehen. Mit validationMode="onChange" und validationDebounceTime läuft es beim Tippen, ohne bei jeder Taste zu feuern. Probiere „ada“.
Erforderlich und optional
Setze indicator auf einer FieldGroup, einem FieldSet oder einem Field, und jedes Label darin markiert sich anhand des required-Attributs seines Steuerelements. "optional" kennzeichnet die Felder, die man überspringen kann, was ruhiger wirkt, wenn die meisten Felder Pflicht sind. "required" fügt ein Sternchen hinzu. Die Markierung ist für Screenreader verborgen, da das Steuerelement sie bereits ansagt.
Status
<FieldStatus /> zeichnet einen Haken, sobald ein bearbeitetes Feld die Validierung besteht, und zeigt ein Warn-Icon, solange sie fehlschlägt. Es folgt dem validationMode des Felds und beurteilt ein Feld daher nie, bevor die Validierung gelaufen ist.
Zeichenzähler
<FieldCounter /> findet das Textsteuerelement in seinem Feld und zählt gegen dessen maxLength. Es lauscht nur, sodass das Tippen nie verlangsamt oder verändert wird.
Fehler aus einer Formularbibliothek oder vom Server
Übergib invalid an das Feld und ein errors-Array an <FieldError />. Es nimmt die Form { message }, die React Hook Form und die meisten Schema-Bibliotheken zurückgeben. Duplikate werden verworfen, und mehrere Meldungen werden zu einer Liste. Ändern sich die Meldungen, blenden die neuen ein, und die Höhe passt sich sanft an, sodass nichts darunter springt. Sende leer ab und behebe dann eine Regel nach der anderen.
Checkboxen
Nutze orientation="horizontal", um die Checkbox neben ihr Label zu setzen. In einem <FieldSet /> benennt die Legende die ganze Gruppe.
Auswahlkarten
Umschließe ein ganzes Feld mit <FieldLabel />, damit die Karte das Klickziel ist. Verwende darin <FieldTitle />, da Labels sich nicht verschachteln lassen. Die Karte wird im aktivierten Zustand getönt und zeigt den Fokusring, wenn ihre Checkbox fokussiert ist.
Fieldset
<FieldSet /> gruppiert zusammengehörige Felder unter einer <FieldLegend />, die zum zugänglichen Namen der Gruppe wird. Ordne Felder mit einem einfachen Grid nebeneinander an.
Responsive
orientation="responsive" stapelt Label und Steuerelement bei wenig Platz und setzt sie nebeneinander, sobald das umgebende <FieldGroup /> breit genug ist. Es reagiert auf die Breite der Gruppe, nicht des Fensters.
Deaktiviert
Das Deaktivieren eines <FieldSet /> deaktiviert jedes Feld und Steuerelement darin. Übergib disabled an ein einzelnes <Field />, um nur dieses zu deaktivieren.
Langer Inhalt
Labels, Beschreibungen und Fehler werden in schmalen Formularen umgebrochen, auch Strings ohne Umbruchstelle, und machen das Layout nie breiter.
Rechts nach links
Text, Checkbox-Platzierung und Fehlerlisten folgen der Leserichtung.
- Label, Beschreibung und sichtbare Fehler sind automatisch mit dem Steuerelement verknüpft, sodass Screenreader alle drei ansagen, wenn es fokussiert wird.
- Ungültige Steuerelemente erhalten
aria-invalid, was auch ihren Fehlerring zeichnet. - Fehler sind keine Live-Regionen. Sie werden vorgelesen, wenn das Steuerelement fokussiert wird, sodass die Validierung bei Änderungen das Tippen nicht unterbricht. Setze beim Absenden den Fokus auf das erste ungültige Feld.
- Fehler wachsen und blenden an Ort und Stelle ein, statt Inhalt nach unten zu schieben. Bei reduzierter Bewegung erscheinen sie ohne Animation.
Basiert auf dem Base UI Field und Fieldset. Jeder Teil akzeptiert die Props des Elements oder der Primitive, die er rendert.
| Prop | Typ | Standard |
|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" |
indicatorMarkiert das Label anhand des required-Attributs des Steuerelements. Wird von FieldGroup oder FieldSet übernommen. | "required" | "optional" | null | – |
nameIdentifiziert das Feld beim Absenden des Formulars. | string | – |
validateGib eine oder mehrere Meldungen zurück, um zu scheitern, oder nichts, um zu bestehen. Asynchron wird unterstützt. | (value, formValues) => string | string[] | null | Promise<…> | – |
validationMode | "onSubmit" | "onBlur" | "onChange" | "onSubmit" |
validationDebounceTimeMillisekunden, die zwischen onChange-Validierungen gewartet wird. | number | 0 |
invalidAus einer Formularbibliothek oder Serverantwort setzen. | boolean | – |
disabled | boolean | false |
dirty | boolean | – |
touched | boolean | – |
actionsRefDas Feld imperativ validieren. | RefObject<{ validate: () => void }> | – |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribut | Beschreibung |
|---|---|
data-slot="field" | Felder in CSS ansprechen. |
data-orientation | Die aktuelle Orientierung. |
data-disabled | Vorhanden, wenn das Feld deaktiviert ist. |
data-valid | Vorhanden, wenn das Feld gültig ist. |
data-invalid | Vorhanden, wenn das Feld ungültig ist. |
data-dirty | Vorhanden, sobald sich der Wert vom Anfangswert geändert hat. |
data-touched | Vorhanden, sobald das Steuerelement fokussiert und wieder verlassen wurde. |
data-filled | Vorhanden, wenn das Steuerelement einen Wert hat. |
data-focused | Vorhanden, solange das Steuerelement den Fokus hat. |
| Prop | Typ | Standard |
|---|---|---|
nativeLabelAuf false setzen, wenn render das Label durch ein Nicht-Label-Element ersetzt. | boolean | true |
optionalTextText, der mit indicator="optional" angezeigt wird. | ReactNode | "Optional" |
render | ReactElement | (props, state) => ReactElement | <label> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-label" | Labels in CSS ansprechen. Außerhalb eines Felds rendert es ein einfaches Label, so funktionieren Auswahlkarten. |
data-disabled | Vorhanden, wenn das Feld deaktiviert ist. |
data-valid | Vorhanden, wenn das Feld gültig ist. |
data-invalid | Vorhanden, wenn das Feld ungültig ist. |
data-dirty | Vorhanden, sobald sich der Wert vom Anfangswert geändert hat. |
data-touched | Vorhanden, sobald das Steuerelement fokussiert und wieder verlassen wurde. |
data-filled | Vorhanden, wenn das Steuerelement einen Wert hat. |
data-focused | Vorhanden, solange das Steuerelement den Fokus hat. |
Ein Icon, das die Gültigkeit des Felds widerspiegelt. Es ist dekorativ, da die Fehlermeldung die Bedeutung trägt.
| Attribut | Beschreibung |
|---|---|
data-slot="field-status" | Das Status-Icon in CSS ansprechen. |
| Prop | Typ | Standard |
|---|---|---|
threshold | number | 10% of maxLength, at most 20 |
announcementMeldung für Screenreader, wenn die Zeichenzahl den Schwellenwert überschreitet oder das Limit erreicht. | (remaining: number) => string | – |
| Attribut | Beschreibung |
|---|---|
data-slot="field-counter" | Den Zähler in CSS ansprechen. |
data-state="near" | "limit" | Vorhanden innerhalb des Schwellenwerts und am Limit. |
| Prop | Typ | Standard |
|---|---|---|
render | ReactElement | (props, state) => ReactElement | <p> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-description" | Beschreibungen in CSS ansprechen. |
data-disabled | Vorhanden, wenn das Feld deaktiviert ist. |
data-valid | Vorhanden, wenn das Feld gültig ist. |
data-invalid | Vorhanden, wenn das Feld ungültig ist. |
data-dirty | Vorhanden, sobald sich der Wert vom Anfangswert geändert hat. |
data-touched | Vorhanden, sobald das Steuerelement fokussiert und wieder verlassen wurde. |
data-filled | Vorhanden, wenn das Steuerelement einen Wert hat. |
data-focused | Vorhanden, solange das Steuerelement den Fokus hat. |
| Prop | Typ | Standard |
|---|---|---|
matchNur bei diesem Validitätsproblem anzeigen. true zeigt es immer. | boolean | "valueMissing" | "typeMismatch" | "tooShort" | "tooLong" | "patternMismatch" | "rangeOverflow" | "rangeUnderflow" | "stepMismatch" | "badInput" | "customError" | "valid" | – |
errorsFehler aus einer Formularbibliothek oder vom Server. Werden angezeigt, wenn die Liste eine Meldung enthält. | Array<{ message?: string } | undefined> | – |
childrenStandardmäßig die Validierungsmeldung. | ReactNode | – |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-error" | Fehler in CSS ansprechen. |
data-starting-style | Vorhanden, während der Fehler hereinwächst. |
data-ending-style | Vorhanden, während der Fehler einklappt. |
data-disabled | Vorhanden, wenn das Feld deaktiviert ist. |
data-valid | Vorhanden, wenn das Feld gültig ist. |
data-invalid | Vorhanden, wenn das Feld ungültig ist. |
data-dirty | Vorhanden, sobald sich der Wert vom Anfangswert geändert hat. |
data-touched | Vorhanden, sobald das Steuerelement fokussiert und wieder verlassen wurde. |
data-filled | Vorhanden, wenn das Steuerelement einen Wert hat. |
data-focused | Vorhanden, solange das Steuerelement den Fokus hat. |
Stapelt Label, Beschreibung und Fehler neben einem Steuerelement in einem horizontalen Feld.
| Prop | Typ | Standard |
|---|---|---|
render | ReactElement | (props, state) => ReactElement | <div> |
Ein Titel im Label-Stil für Inhalte in einer <FieldLabel />, etwa Auswahlkarten.
| Prop | Typ | Standard |
|---|---|---|
render | ReactElement | (props, state) => ReactElement | <div> |
Setzt Felder auseinander und ist der Container, den responsive Felder messen.
| Prop | Typ | Standard |
|---|---|---|
indicatorGilt für jedes Feld darin. | "required" | "optional" | null | – |
render | ReactElement | (props, state) => ReactElement | <div> |
| Prop | Typ | Standard |
|---|---|---|
indicatorGilt für jedes Feld darin. | "required" | "optional" | null | – |
disabledDeaktiviert jedes Feld darin. | boolean | false |
render | ReactElement | (props, state) => ReactElement | <fieldset> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-set" | Fieldsets in CSS ansprechen. |
data-disabled | Vorhanden, wenn das Fieldset deaktiviert ist. |
| Prop | Typ | Standard |
|---|---|---|
variantlabel entspricht der Größe eines Feld-Labels. | "legend" | "label" | "legend" |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-legend" | Legenden in CSS ansprechen. |
data-variant | Die aktuelle Variante. |
Ein <Separator /> mit Abständen für Formulare, das alle seine Props akzeptiert.
| Prop | Typ | Standard |
|---|---|---|
childrenOptionaler Text, der in der Mitte der Linie angezeigt wird. | ReactNode | – |
alignWo der Text auf der Linie sitzt. | "start" | "center" | "end" | "center" |
decorativeVerbirgt eine einfache Linie vor Screenreadern, wenn sie nur visuell ist. | boolean | false |
render | ReactElement | (props, state) => ReactElement | <div> |
| Attribut | Beschreibung |
|---|---|
data-slot="field-separator" | Feld-Trennzeichen in CSS ansprechen. |
data-content | Vorhanden, wenn das Trennzeichen Text hat. |
data-slot="separator-label" | Das Element, das den Text umschließt. |
Umschließt eine Checkbox oder ein Radio samt Label in einer Gruppe, sodass sich jeder Eintrag einzeln deaktivieren lässt.
| Prop | Typ | Standard |
|---|---|---|
disabled | boolean | false |
render | ReactElement | (props, state) => ReactElement | <div> |
Rendert beliebige Inhalte aus dem Validitätszustand des Felds, zum Beispiel eine Stärkeanzeige oder einen Zeichenzähler.
| Prop | Typ | Standard |
|---|---|---|
children | (state: { validity, errors, error, value }) => ReactNode | – |
- InputEin Texteingabefeld mit drei Größen, ungültigen und schreibgeschützten Zuständen, nativem Validierungsstyling und einer 16-px-Schrift für Touch, damit Smartphones nie hineinzoomen.
- MotionDie Easing-Kurven, Dauern und der Reduced-Motion-Check, mit denen jede Komponente animiert, plus Hooks für Größen-Morphs und gleitende Hervorhebungen.
- SeparatorEine Haarlinie, die Inhalte horizontal oder vertikal trennt, mit optionalem Label und einem dekorativen Modus für rein visuelle Linien.
- useComposedRefBehält eine Ref auf dein eigenes Element und leitet sie trotzdem an die Ref weiter, die der Parent übergeben hat.
- useMergedRefKombiniert beliebig viele Callback- und Objekt-Refs zu einem, mit React-19-Ref-Cleanup für jeden von ihnen.
- CalendarEin Datumsraster für Einzel-, Bereichs- und Mehrfachauswahl, mit gleitenden Monaten, Bereichsvorschau und Tagen in Touch-Größe.
In Blocks verwendet
Blocks, die auf Field aufbauen.
- API keysDie API-Schlüssel-Seite eines KI-Produkts, wie in den Konsolen von OpenAI und Anthropic. Schlüssel mit eingeschränkten Berechtigungen und Ablaufdatum erstellen, das Secret einmal sehen mit einem Kopieren, das sich bestätigt, mit Rückgängig widerrufen, direkt umbenennen, mit Übergangsfrist rotieren und die Nutzung pro Schlüssel sehen.
- BillingPlan & Nutzung für ein KI-Produkt, im Stil von Cursor, Claude und Vercel. Eine nach Modell aufgeteilte Nutzungsanzeige, die das Ende des Zyklus hochrechnet und warnt, bevor die Credits ausgehen, ein tägliches Diagramm zum Scrubben, ein Ausgabenlimit mit Warnungen, die du auf der Anzeige in der Vorschau siehst, Planwechsel mit exakter Anteilsberechnung, ein Kartenformular mit echter Validierung und Rechnungen als PDF-Download.
- ModelsDie Modelle-Seite in den Einstellungen eines KI-Produkts. Ein Standardmodell mit Kontext, Geschwindigkeit und Kosten auf einen Blick, ein Standard-Effort, der weiß, was jedes Modell unterstützt, eine durchsuchbare Modellliste nach Anbieter gruppiert mit Filtern, Pins und Sammelschaltern, OpenAI-kompatible Server mit echtem Verbindungstest und ein Refresh, der dir sagt, was neu ist.
- NotificationsDer Bereich „Benachrichtigungen“ in den Einstellungen eines KI-Produkts. Ein Raster aus Kanal und Ereignis mit Toggles für Zeile, Spalte und alle, Ruhezeiten mit einer Live-Zeile zur nächsten Ruhephase, ein E-Mail-Digest, echte Testsendungen für Desktop, E-Mail, Push und Slack, Umgang mit Browser-Berechtigungen und ein Slack-Verbindungsablauf. Passt in jeden Settings-Bereich.