Input · Documentation

UIEntrées

Champs de texte fiables pour les formulaires de produitsLien vers la section

Les Entrées component est un contrôle de formulaire fondamental dans PyColors UI.

Utilisez-le pour:

Formulaires de connexion
champs de recherche
formulaires de paramètres
détails de facturation
champs de profil
Filtres d'administration
Flux de création de produits
Formulaires pilotés par validation

L'entrée est conçue pour être accessible par défaut, sensible au thème et suffisamment flexible pour des champs simples ou des mises en page de formulaire de production.

Il soutient:

étiquettes
Texte d'aide
Erreurs de validation
Icônes gauche et droite
Variantes de taille
support clavier et lecteur d'écran

Idée de base

Input collecte les données des utilisateurs. Les règles de validation doivent résider dans votre calque de formulaire ou de schéma, et non dans la primitive visuelle.

ImportationLien vers la section

input-import.tsx

import { Input, type InputProps, type InputSize } from "@pycolors/ui";

Utilisation de baseLien vers la section

Utilisez Input lorsque le champ est simple et que le contexte environnant fournit déjà une étiquette.

Règle des étiquettes

Le texte d'espace réservé n'est pas un remplacement pour une étiquette. Utilisation label lorsque le terrain doit être seul.

Avec étiquette et texte d'aideLien vers la section

Utilisation label et helperText pour rendre le champ auto-explicatif.

We’ll never share your email.

Quand utiliser InputLien vers la section

Utilisez la saisie lorsque l'utilisateur doit fournir ou modifier de courtes données textuelles.

Formulaires

Utilisation pour les formulaires de compte, de profil, de facturation, d'organisation et de configuration.

Rechercher

Utilisez avec une icône de premier plan pour la recherche, les filtres et les champs de recherche rapide.

Validation

Use error to show field-level validation feedback clearly.

Erreur de validationLien vers la section

Quand error est fourni :

Les styles d'erreur sont appliqués
aria-invalid est fixé
Le texte de l'erreur est connecté au champ via aria-describedby et aria-errormessage
Le texte de l'erreur a role="alert", il est donc annoncé immédiatement lorsqu'il apparaît - y compris lorsque le champ est déjà concentré, pas seulement sur le prochain événement focus
un consommateur fourni aria-describedby est composé avec les propres helper/error ids du champ plutôt que remplacé, donc les deux descriptions restent disponibles pour la technologie d'assistance

Invalid email address

Règle de validation

Gardez les erreurs courtes et spécifiques. L'utilisateur doit immédiatement comprendre ce qu'il faut réparer.

Avec icônesLien vers la section

Utilisez des icônes lorsqu'elles clarifient le but du champ.

Icône gaucheLien vers la section

Icône de droiteLien vers la section

Projet

Règle d'icône

Les icônes devraient soutenir le sens. Ne comptez pas sur une icône comme seule étiquette.

TaillesLien vers la section

Utilisez la taille pour adapter la densité sur toutes les surfaces du produit.

Tailles disponiblesLien vers la section

Taille	Objet
`sm`	Interfaces utilisateur denses, tableaux, filtres, barres d'outils compactes
`md`	Taille de saisie par défaut
`lg`	Onboarding, auth, formes marketing, flux proéminents

Règle de densité

Utilisation md par défaut. Utilisation sm pour les surfaces de produits denses et lg lorsque la forme a besoin d'une plus grande importance.

UtilisationsLien vers la section

Commencez par l'objectif du champ

Utilisez une étiquette claire lorsque le champ doit être isolé. Ne vous fiez pas au texte d'espace réservé.

Ajouter du texte d'aide uniquement lorsqu'il est utile

Le texte d'aide devrait réduire l'incertitude, pas expliquer les champs évidents.

Gardez la validation à proximité du champ

Les erreurs au niveau du champ doivent apparaître directement en dessous de l'entrée affectée.

Utiliser les icônes avec parcimonie

Les icônes fonctionnent bien pour la recherche, l'URL, la devise ou les signaux spécifiques au domaine.

Gardez les règles commerciales en dehors de la primitive

Utilisez Zod, React Hook Form, la validation du serveur ou votre couche de domaine pour la logique de validation.

Entrée vs Mot de passeInput vs TextareaLien vers la section

Situation	Utilisation
Valeur de texte court	Entrées
Email, nom, slug, URL	Entrées
Mot de passe avec révélation	PasswordInput
Contenu long et libre	Textarea ou champ personnalisé
Champ de recherche	Entrée avec icône principale
Entrée numérique ou monétaire	Entrée avec formatage spécifique au domaine
Choisissez-en un parmi les options fixes	Sélectionnez, RadioGroup ou Tabs selon UX

Règle de décision

Utilisez Input pour le texte court. Utilisez PasswordInput pour les secrets. Utilisez un champ plus grand pour le contenu long.

APILien vers la section

Props

Prop	Type	Par défaut	Désignation
`label`	`string`	—	Étiquette accessible au-dessus du champ
`helperText`	`string`	—	Texte d'aide sous le champ
`error`	`string`	—	Message d'erreur de validation
`leftIcon`	`React.ReactNode`	—	Icône affichée à gauche
`rightIcon`	`React.ReactNode`	—	Icône affichée à droite
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Densité visuelle
`className`	`string`	—	Dépassement du vent arrière

L'entrée étend les props d'entrée standard, à l'exclusion de la size attribut.

input-props.ts

React.InputHTMLAttributes<HTMLInputElement>;

TypeScript typesLien vers la section

input-types.ts

export type InputSize = "sm" | "md" | "lg";

export interface InputProps extends Omit<
  React.InputHTMLAttributes<HTMLInputElement>,
  "size"
> {
  label?: string;
  helperText?: string;
  error?: string;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  size?: InputSize;
}

AccessibilitéLien vers la section

L'entrée est conçue pour prendre en charge la composition de formulaire accessible.

Directives :

Utiliser un visible label quand le terrain a besoin de contexte
Ne vous fiez pas au texte d'espace réservé comme seule étiquette
error devrait fixer aria-invalid
helper et le texte d'erreur doivent être connectés via aria-describedby
texte d'erreur est également annoncé en direct via role="alert" Le moment où il apparaît
disabled réduit le champ et affiche un curseur non autorisé sur le champ lui-même, pas seulement sur l'attribut natif - l'état visuel et l'état fonctionnel correspondent toujours
icônes décoratives devraient utiliser aria-hidden="true"
Gardez les anneaux de focus visibles
Utiliser un natif approprié type valeurs, telles que email, url, telou search
utilisation autoComplete valeurs, le cas échéant

Règle d'accessibilité

Chaque entrée a besoin d'un nom accessible. Une étiquette visible est généralement le choix le plus sûr.

Préférez/évitezLien vers la section

Préférez

Étiquettes visibles pour les champs importants
Texte d'aide court
Messages de validation spécifiques
Types d'entrée sémantiques
Tailles cohérentes dans une forme

Éviter

Champs réservés
erreurs vagues comme “Invalide”
trop d'icônes dans un champ
mélange aléatoire des tailles d'entrée
mettre des règles de validation à l'intérieur de la primitive UI

Directives de copie du produitLien vers la section

Les étiquettes, les espaces réservés, le texte d'aide et les erreurs ont chacun un travail différent.

Exemples d'étiquettes

Courriel, nom du projet, entreprise, site Web, courriel de facturation, nom de l'espace de travail.

Questions courantesLien vers la section

Formulaires avec validationUtilisez la saisie avec React Hook Form, Zod et les états de validation clairs.PasswordInputUtilisez pour les champs de mot de passe sécurisés avec le comportement de bascule de révélation.TypographieÉtiquettes, texte d'aide et erreurs alignés avec l'échelle de type.AccessibilitéCréez des contrôles de formulaire accessibles avec des étiquettes, des descriptions et des erreurs.