{"id":22208486,"url":"https://github.com/forthtilliath/react-use-form-fields-ref","last_synced_at":"2025-10-13T04:30:25.725Z","repository":{"id":173336098,"uuid":"649444978","full_name":"Forthtilliath/react-use-form-fields-ref","owner":"Forthtilliath","description":"useFormFieldsRef simplifies managing form fields in a React component","archived":false,"fork":false,"pushed_at":"2024-02-05T07:18:09.000Z","size":785,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-08T17:43:58.535Z","etag":null,"topics":["customhook","customhooksreact","field","form","react","useref-hook"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@forthtilliath/react-use-form-fields-ref","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Forthtilliath.png","metadata":{"files":{"readme":"README.fr.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-06-04T21:23:58.000Z","updated_at":"2024-01-24T15:02:51.000Z","dependencies_parsed_at":"2023-09-27T21:36:00.938Z","dependency_job_id":null,"html_url":"https://github.com/Forthtilliath/react-use-form-fields-ref","commit_stats":null,"previous_names":["forthtilliath/react-use-form-fields-ref"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forthtilliath%2Freact-use-form-fields-ref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forthtilliath%2Freact-use-form-fields-ref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forthtilliath%2Freact-use-form-fields-ref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forthtilliath%2Freact-use-form-fields-ref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Forthtilliath","download_url":"https://codeload.github.com/Forthtilliath/react-use-form-fields-ref/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236298326,"owners_count":19126501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["customhook","customhooksreact","field","form","react","useref-hook"],"created_at":"2024-12-02T19:19:46.130Z","updated_at":"2025-10-13T04:30:20.433Z","avatar_url":"https://github.com/Forthtilliath.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-use-form-fields-ref\n\n[![en](https://img.shields.io/badge/lang-en-green.svg)](https://github.com/Forthtilliath/react-use-form-fields-ref/blob/main/README.md) [![fr](https://img.shields.io/badge/lang-fr-blue.svg)](https://github.com/Forthtilliath/react-use-form-fields-ref/blob/main/README.fr.md)\n\n## Introduction\n\n[![npm version](https://img.shields.io/npm/v/@forthtilliath/react-use-form-fields-ref?\u0026label=version\u0026style=flat-square)](https://img.shields.io/npm/v/@forthtilliath/react-use-form-fields-ref?label=version\u0026style=flat-square) [![npm download](https://img.shields.io/npm/dt/@forthtilliath/react-use-form-fields-ref?style=flat-square)](https://img.shields.io/npm/dt/@forthtilliath/react-use-form-fields-ref?style=flat-square) [![github repo size](https://img.shields.io/github/repo-size/Forthtilliath/react-use-form-fields-ref?style=flat-square)](https://img.shields.io/github/repo-size/Forthtilliath/react-use-form-fields-ref?style=flat-square) [![licence](https://img.shields.io/npm/l/@forthtilliath/react-use-form-fields-ref?style=flat-square)](https://img.shields.io/npm/l/@forthtilliath/react-use-form-fields-ref?style=flat-square)\n\nLe package `@forthtilliath/react-use-form-fields-ref` est une bibliothèque qui fournit un hook React appelé `useFormFieldsRef`. Ce hook vous permet de gérer les références de champs de formulaire dans un composant React. Il renvoie un tableau contenant deux éléments : un objet qui contient les références pour chaque champ, et un objet qui contient des fonctions pour interagir avec ces références.\n\nLe hook `useFormFieldsRef` est utile pour simplifier la gestion des champs de formulaire dans un composant React. Il facilite la définition de références pour chaque champ et l'interaction avec ces références de manière cohérente. Le package `@forthtilliath/react-use-form-fields-ref` est facile à utiliser et peut être installé via NPM, Yarn ou PNPM.\n\n## Installation\n\nInstallez-le depuis npm et incluez-le dans votre processus de construction React\n\n```bash\nnpm install --save @forthtilliath/react-use-form-fields-ref\n```\n\nou depuis yarn :\n\n```bash\nyarn add --dev @forthtilliath/react-use-form-fields-ref\n```\n\nou depuis pnpm :\n\n```bash\npnpm install --save @forthtilliath/react-use-form-fields-ref\n```\n\n## Usage\n\nVoici un exemple de formulaire montrant comment utiliser le hook ``useFormFieldsRef`` pour gérer les références des champs de saisie, des boutons radio et d'une liste déroulante :\n\n__JSX__\n\n```jsx\nimport { useFormFieldsRef } from \"@forthtilliath/react-use-form-fields-ref\";\n\nexport function MyForm() {\n  const [\n    fieldsRef,\n    { setRef, getRef, getField, getAllRef, getFormData, isFieldNotNull },\n  ] = useFormFieldsRef([\"username\", \"password\", \"gender\", \"message\", \"age\"]);\n\n  const handleSubmit = () =\u003e {\n    const usernameField = getField(\"username\");\n    if (isFieldNotNull(usernameField)) {\n      console.log(usernameField.value);\n    }\n    console.log(getRef(\"age\"));\n    console.log(getAllRef());\n    console.log(Object.fromEntries(getFormData()));\n  };\n\n  return (\n    \u003cform onSubmit={handleSubmit}\u003e\n      {/* Exemples avec des champs de saisie */}\n      \u003cinput type=\"text\" ref={setRef(\"username\")} placeholder=\"Nom d'utilisateur\" /\u003e\n      \u003cinput type=\"password\" ref={setRef(\"password\")} placeholder=\"Mot de passe\" /\u003e\n\n      {/* Exemples avec des boutons radio */}\n      \u003clabel\u003e\n        \u003cspan\u003eMineur :\u003c/span\u003e\n        \u003cinput type=\"radio\" name=\"age\" ref={setRef(\"age\")} value=\"mineur\" /\u003e\n      \u003c/label\u003e\n      \u003clabel\u003e\n        \u003cspan\u003eMajeur :\u003c/span\u003e\n        \u003cinput type=\"radio\" name=\"age\" ref={setRef(\"age\")} value=\"majeur\" /\u003e\n      \u003c/label\u003e\n\n      {/* Exemples avec des listes déroulantes */}\n      \u003cselect ref={setRef(\"gender\")} defaultValue={\"default\"}\u003e\n        \u003coption value=\"default\" disabled\u003e\n          Genre\n        \u003c/option\u003e\n        \u003coption value=\"male\"\u003eHomme\u003c/option\u003e\n        \u003coption value=\"female\"\u003eFemme\u003c/option\u003e\n        \u003coption value=\"other\"\u003eAutre\u003c/option\u003e\n      \u003c/select\u003e\n\n      \u003ctextarea ref={setRef(\"message\")} placeholder=\"Message\" /\u003e\n      \u003cbutton type=\"submit\"\u003eEnvoyer\u003c/button\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\n__TSX__\n\n```tsx\nimport { useFormFieldsRef } from \"@forthtilliath/react-use-form-fields-ref\";\n\nexport function MyForm() {\n  const [\n    fieldsRef,\n    { setRef, getRef, getField, getAllRef, getFormData, isFieldNotNull },\n  ] = useFormFieldsRef([\"username\", \"password\", \"gender\", \"message\", \"age\"]);\n\n  const handleSubmit: React.FormEventHandler\u003cHTMLFormElement\u003e = () =\u003e {\n    const usernameField = getField(\"username\");\n    if (isFieldNotNull(usernameField)) {\n      console.log(usernameField.value);\n    }\n    console.log(getRef(\"age\"));\n    console.log(getAllRef());\n    console.log(Object.fromEntries(getFormData()));\n  };\n\n  return (\n    \u003cform onSubmit={handleSubmit}\u003e\n      {/* Exemples avec des champs de saisie */}\n      \u003cinput type=\"text\" ref={setRef(\"username\")} placeholder=\"Nom d'utilisateur\" /\u003e\n      \u003cinput type=\"password\" ref={setRef(\"password\")} placeholder=\"Mot de passe\" /\u003e\n\n      {/* Exemples avec des boutons radio */}\n      \u003clabel\u003e\n        \u003cspan\u003eMineur :\u003c/span\u003e\n        \u003cinput type=\"radio\" name=\"age\" ref={setRef(\"age\")} value=\"mineur\" /\u003e\n      \u003c/label\u003e\n      \u003clabel\u003e\n        \u003cspan\u003eMajeur :\u003c/span\u003e\n        \u003cinput type=\"radio\" name=\"age\" ref={setRef(\"age\")} value=\"majeur\" /\u003e\n      \u003c/label\u003e\n\n      {/* Exemples avec des listes déroulantes */}\n      \u003cselect ref={setRef(\"gender\")} defaultValue={\"default\"}\u003e\n        \u003coption value=\"default\" disabled\u003e\n          Genre\n        \u003c/option\u003e\n        \u003coption value=\"male\"\u003eHomme\u003c/option\u003e\n        \u003coption value=\"female\"\u003eFemme\u003c/option\u003e\n        \u003coption value=\"other\"\u003eAutre\u003c/option\u003e\n      \u003c/select\u003e\n\n      \u003ctextarea ref={setRef(\"message\")} placeholder=\"Message\" /\u003e\n      \u003cbutton type=\"submit\"\u003eEnvoyer\u003c/button\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\nLe code utilise le hook ``useFormFieldsRef`` pour créer une référence pour chaque champ de saisie dans le formulaire. Cette fonction renvoie un tableau contenant deux éléments : un objet de références pour chaque champ de saisie, et un objet contenant des fonctions pour interagir avec les références.\n\nUne fois les références créées, le code définit les champs de saisie du formulaire en utilisant les éléments JSX ``\u003cinput\u003e``, ``\u003cselect\u003e`` et ``\u003ctextarea\u003e``. Pour chaque champ de saisie, il utilise la fonction ``setRef`` fournie par ``useFormFieldsRef`` pour créer une référence.\n\nLorsque l'utilisateur soumet le formulaire en cliquant sur le bouton \"Submit\", le code appelle la fonction ``handleSubmit``, qui utilise les fonctions fournies par ``useFormFieldsRef`` pour accéder aux valeurs actuelles des champs de saisie, et les affiche dans la console.\n\n## Ce que retourne useFormFieldsRef\n\nLe hook `useFormFieldsRef` renvoie un tableau contenant deux éléments :\n\n- Le premier élément est un objet `useRef` initialisé avec un objet contenant des valeurs ``null`` pour chaque champ de saisie.\n- Le deuxième élément est un objet contenant des fonctions pour interagir avec l'objet `useRef`.\n\n\n### Premier élément : objet `useRef`\n\nDans le code donné, on peut voir que le premier élément d'un tableau renvoyé par la fonction useFormFieldsRef correspond à un objet de références pour chaque champ de saisie. On peut y accéder de la manière suivante :\n\n__JSX / TSX__\n\n```tsx\nconst [myFormRef, actions] = useFormFieldsRef(myFields);\n\n// Met le focus sur le champ `username` si celui-ci est vide\nconst checkInput = () =\u003e {\n  // myInput has the type HTMLFieldElement | null\n  // Le type HTMLFieldElement est union type\n  // HTMLFieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement\n  const myInput = refs.current.username;\n  if (myInput \u0026\u0026 myInput.value === \"\") {\n    myInput.focus();\n  }\n};\n```\nIci, on peut voir que ``refs.current.username`` correspond à la référence du champ ``username``. Cette référence peut être utilisée pour accéder à la valeur actuelle du champ de saisie.\n\n### Second élément : ``actions``\n\nLe second élément est un objet qui contient toutes les actions. Voici une liste de ces fonctions avec une brève description de ce qu'elles font : \n\n* `getFieldsRef` : renvoie un objet qui contient les références pour chaque champ.\n* `setRef` : renvoie une fonction qui prend un élément `HTMLInputElement`, `HTMLSelectElement` ou `HTMLTextAreaElement` en argument et définit la référence pour le champ correspondant au nom donné.\n* `getRef` : renvoie la référence pour le champ correspondant au nom donné.\n* `getField` : renvoie un objet contenant la référence et la valeur pour le champ correspondant au nom donné.\n* `getAllRefs` : renvoie un objet contenant toutes les références pour chaque champ.\n* `getFormData` : renvoie un tableau contenant des paires clé-valeur pour chaque champ.\n* `isFieldNotNull` : renvoie `true` si le champ n'est pas nul, `false` sinon.\n\n#### setRef\n\n`setRef` renvoie un rappel utilisé pour mettre à jour la référence liée à la clé donnée.\n\n__JSX / TSX__\n\n```tsx\n\u003cinput type=\"text\" ref={setRef(\"username\")} placeholder=\"Username\" /\u003e\n```\n\nDans cet exemple, ``setRef(\"username\")`` est utilisé pour créer une référence pour le champ de saisie.\n\n#### getRef\n\n``getRef`` renvoie la valeur contenue dans la référence ``fieldsRef`` pour la clé donnée. Un bouton radio renverra une chaîne vide.\n\n__JSX / TSX__\n\n```tsx\nconst [, { getRef }] = useFormFieldsRef([\"username\", \"password\"]);\n\nconst handleSubmit = () =\u003e {\n  console.log(getRef(\"username\"));\n};\n```\n\nLe code crée des références pour les champs de saisie \"username\" et \"password\" et utilise ``getRef`` pour obtenir la valeur du champ de saisie \"username\" lorsque ``handleSubmit`` est appelée et l'afficher.\n\n#### getField\n\n`getField` renvoie l'élément contenu dans la référence `fieldsRef` pour la clé donnée. Un bouton radio renverra un tableau d'entrées qui contient des `HTMLInputElement` de la clé donnée.\n\n__JSX__\n\n```jsx\nconst [, { getField }] = useFormFieldsRef([\"username\", \"password\"]);\n\nconst checkInput = () =\u003e {\n  const myUsernameInput = getField(\"username\");\n  if (myUsernameInput.value === \"\") {\n    myUsernameInput.focus();\n  }\n};\n```\n\n__TSX__\n\n```tsx\nconst [, { getField }] = useFormFieldsRef([\"username\", \"password\"]);\n\nconst checkInput = () =\u003e {\n  const myUsernameInput = getField\u003cHTMLInputElement\u003e(\"username\");\n  if (myUsernameInput.value === \"\") {\n    myUsernameInput.focus();\n  }\n};\n```\n\nLe code crée une référence pour le champ de saisie \"username\" en utilisant `useFormFieldsRef`, et utilise `getField` pour obtenir la valeur du champ de saisie \"username\" lorsque `checkInput` est appelée. Si la valeur du champ de saisie est une chaîne vide, `checkInput` met le focus sur le champ de saisie \"username\".\n\n#### getAllRef\n\n`getAllRef` renvoie un objet contenant des valeurs à partir d'une liste de références d'entrée.\n\n__JSX / TSX__\n\n```tsx\nconst [, { getAllRef }] = useFormFieldsRef([\"username\", \"password\"]);\n\nconst handleSubmit = () =\u003e {\n  console.log(getAllRef());\n};\n```\n\nLe code crée des références pour les champs de saisie \"username\" et \"password\" en utilisant ``useFormFieldsRef``, et utilise ``getAllRef`` pour obtenir les valeurs des deux champs de saisie lorsque ``handleSubmit`` est appelée et les afficher dans la console.\n\n#### getFormData\n\n`getFormData` récupère les données d'un formulaire à partir des champs de saisie et les renvoie sous forme d'un objet ``FormData``.\n\n__JSX / TSX__\n\n```tsx\nconst [, { getFormData }] = useFormFieldsRef([\"username\", \"password\"]);\n\nconst handleSubmit = () =\u003e {\n  console.log(Object.fromEntries(getFormData()));\n};\n```\n\nLe code crée des références pour les champs de saisie \"username\" et \"password\" en utilisant ``useFormFieldsRef``, et définit une fonction ``getFormData`` qui renvoie un objet ``FormData`` contenant les valeurs des champs de saisie. Lorsque ``handleSubmit`` est appelée, le code affiche un objet contenant les valeurs des champs de saisie dans la console.\n\n#### isFieldNotNull\n\n`isFieldNotNull` est une fonction qui vérifie si un élément ``HTMLFieldElement`` donné n'est pas nul.\n\n__JSX__\n\n```jsx\nconst focusIfEmpty = (key) =\u003e {\n  const field = getField(key);\n  if (isFieldNotNull(field)) {\n    if (field.value === \"\") field.focus();\n  } else {\n    throw new Error(`The field with ${key} key is null`);\n  }\n};\n```\n\n__TSX__\n\n```tsx\ntype InputKey = (typeof inputsName)[number];\n\nconst focusIfEmpty = (key: InputKey) =\u003e {\n  const field = getField(key);\n  if (isFieldNotNull(field)) {\n    if (field.value === \"\") field.focus();\n  } else {\n    throw new Error(`The field with ${key} key is null`);\n  }\n};\n```\n\nLe code définit une fonction ``focusIfEmpty`` qui met le focus sur un champ de saisie s'il est vide, et lance une erreur si le champ est nul.\n\n## Types utilitaires\n\n### UseFormFieldsRefActions\n\n``UseFormFieldsRefActions`` est un type qui aide à obtenir le type de retour du deuxième paramètre d'un hook. Cela peut être utile lorsque vous passez ``setRef`` à un enfant.\n\n__TSX__\n\n```tsx\n// Dans votre composant de formulaire\nexport const connexionInputs = [\"username\", \"password\"] as const;\n\n// Dans votre composant enfant\nimport { UseFormFieldsRefActions } from \"@forthtilliath/react-use-form-fields-ref\";\n\n// Action contient tous les types d'action\ntype InputKey = (typeof connexionInputs)[number];\ntype Action = UseFormFieldsRefActions\u003cInputKey\u003e;\n\ntype Props = {\n  // Notez le setRef pour obtenir uniquement le type de la méthode setRef\n  setRef: Action[\"setRef\"];\n};\n```\n\n## Exemple d'utilisation\n\nConsultez cet [exemple StackBlitz](https://stackblitz.com/edit/react-use-form-fields-ref?file=src%2Fcomponents%2FSignUpForm.tsx) ([version JS](https://stackblitz.com/edit/reactjs-use-form-fields-ref?file=src%2Fcomponents%2FSignUpForm.jsx)) pour voir comment ces fonctions peuvent être utilisées dans un formulaire React .\n\nDans l'exemple, vous pouvez voir comment le crochet `useFormFieldsRef` est utilisé pour gérer les champs du formulaire et comment les autres fonctions peuvent être utilisées pour accéder ou manipuler les données du formulaire. N'hésitez pas à bifurquer l'exemple et à l'expérimenter vous-même !\n\nFaites-moi savoir si vous avez des questions ou des commentaires sur l'exemple.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforthtilliath%2Freact-use-form-fields-ref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforthtilliath%2Freact-use-form-fields-ref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforthtilliath%2Freact-use-form-fields-ref/lists"}