{"id":20705717,"url":"https://github.com/zamarawka/use-validatorjs","last_synced_at":"2026-04-14T04:03:28.273Z","repository":{"id":39301134,"uuid":"390670696","full_name":"zamarawka/use-validatorjs","owner":"zamarawka","description":"Tiny laravel-like data validator for react.","archived":false,"fork":false,"pushed_at":"2025-03-31T21:50:29.000Z","size":305,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-05T23:57:05.194Z","etag":null,"topics":["javascript","npm-package","react","reacthook","typescript"],"latest_commit_sha":null,"homepage":"","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/zamarawka.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-29T09:27:14.000Z","updated_at":"2025-03-31T21:48:24.000Z","dependencies_parsed_at":"2025-03-31T10:34:29.053Z","dependency_job_id":null,"html_url":"https://github.com/zamarawka/use-validatorjs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/zamarawka/use-validatorjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamarawka%2Fuse-validatorjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamarawka%2Fuse-validatorjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamarawka%2Fuse-validatorjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamarawka%2Fuse-validatorjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zamarawka","download_url":"https://codeload.github.com/zamarawka/use-validatorjs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamarawka%2Fuse-validatorjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281577705,"owners_count":26524886,"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","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["javascript","npm-package","react","reacthook","typescript"],"created_at":"2024-11-17T01:19:20.086Z","updated_at":"2025-10-29T06:44:37.745Z","avatar_url":"https://github.com/zamarawka.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ci Status](https://github.com/zamarawka/use-validatorjs/workflows/CI/badge.svg)](https://github.com/zamarawka/use-validatorjs/actions)\n[![Npm version](https://img.shields.io/npm/v/use-validatorjs.svg?style=flat\u0026logo=npm)](https://www.npmjs.com/package/use-validatorjs)\n[![React version](https://img.shields.io/npm/dependency-version/use-validatorjs/peer/react.svg?style=flat\u0026logo=react)](https://reactjs.org/)\n\n# use-validatorjs\n\nTiny tree-shakable package for validation any data-model by rules for [React.js](https://reactjs.org/).\nProvides hook for manage validation state and run validations agnostic from way to input data.\nIt also knows about i18n of your app and don't try to force use of internal translation engine.\n\nPackage includes its TypeScript Definitions\n\n# Install\n\n```sh\nnpm install use-validatorjs\n```\n\n# Usage\n\nValidation rules here - is plain javascript functions.\nWe don't create abstract language based on strings, magic or other spiritual tactics. We use javascript.\nAs result it give us to a lot of pros:\n\n- Easy way to create rules - you should simply write js function\n- Powerful language to describe validation rules - native js structs is flexible\n- Fully type-safe in ts usage - all rules has additional typecheck of validation value\n\n```tsx\nimport useValidator, { required, min } from 'use-validatorjs';\n\n// Some i18n function like https://github.com/zamarawka/i18n-lite#t or https://www.i18next.com/overview/api#t\nfunction t(key, params) {\n  return key;\n}\n\nfunction App() {\n  const data = {\n    some: '',\n    other: 3,\n  };\n\n  const { isErrors, isShowErrors, errors, showErrors, validation } = useValidator(t, data, {\n    some: required, // pass 1 rule\n    other: [required, min(2)], // pass many rules\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cdiv\u003e\n        \u003cdiv\u003eSome: {data.some}\u003c/div\u003e\n        {validation.some \u0026\u0026 \u003cdiv styles={{ color: 'red' }}\u003e{validation.some}\u003c/div\u003e}\n      \u003c/div\u003e\n      \u003cdiv\u003e\n        \u003cdiv\u003eOther: {data.other}\u003c/div\u003e\n        {validation.other \u0026\u0026 \u003cdiv styles={{ color: 'red' }}\u003e{validation.other}\u003c/div\u003e}\n      \u003c/div\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## UI/UX\n\nGood practice is don't shock users untill they try to do something wrong.\nBased on this ideology `useValidator` return 2 objects with errors:\n\n1. `validation` - realtime validation messages\n2. `errors` - empty object untill you need to show errors\n\nTo fill errors object you should use `showErrors` function, which could receive boolean value with state, by default it's `true`.\nTo check current state of view errors you should use `isShowErrors`.\n\nFor example, render validation errors only then form submitted and disable submit button if errors is shown and still exists:\n\n```tsx\nimport useValidator from 'use-validatorjs'; // ... rules here\n\nfunction App() {\n  const data = {\n    // some data object\n  };\n\n  const { isErrors, isShowErrors, errors, showErrors, validation } = useValidator(t, data, {\n    // ... validation rules\n  });\n\n  function handleSubmit() {\n    if (isErrors) {\n      return showErrors();\n    }\n\n    // business logic here: api calls, calculation, etc...\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003cdiv\u003e\n        \u003cdiv\u003eSome: {data.some}\u003c/div\u003e\n        {errors.some \u0026\u0026 \u003cdiv styles={{ color: 'red' }}\u003e{errors.some}\u003c/div\u003e}\n      \u003c/div\u003e\n      \u003cdiv\u003e\n        \u003cdiv\u003eOther: {data.other}\u003c/div\u003e\n        {errors.other \u0026\u0026 \u003cdiv styles={{ color: 'red' }}\u003e{errors.other}\u003c/div\u003e}\n      \u003c/div\u003e\n      \u003cbutton onClick={handleSubmit} disabled={isShowErrors \u0026\u0026 isErrors}\u003e\n        Submit\n      \u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Custom validation rule\n\nYou could create custom validation rule by create implementation for `CheckerFn` type.\n\n`CheckerFn` receive translation function as first argument, validation value as second argument.\nIt should return `undefined` if validation pass or string with validaiton message if validation failed.\n\n`CheckerFn` - is generic type wich await type of validation value.\n\n```tsx\nimport useValidator, { CheckerFn } from 'use-validatorjs';\n\n// Custom validation function\nconst myAwesomeValidation: CheckerFn\u003cnumber | string\u003e = (t, val) =\u003e {\n  if (val !== 'strict-rule') {\n    return t('myAwesomeValidation');\n  }\n};\n\n// Custom validation function with parameters\n// In fact this is any function which return `CheckerFn`\nconst myAwesomeValidationWithParams = (param: number): CheckerFn\u003cnumber\u003e =\u003e (t, val) =\u003e {\n  if (val !== param) {\n    return t('myAwesomeValidationWithParams', { param });\n  }\n}\n\nfunction App() {\n  const data = {\n    some: 'strict-rule'\n    other: 3,\n  };\n\n  const { isErrors, errors } = useValidator(t, data, {\n    some: myAwesomeValidation,\n    other: [myAwesomeValidation, myAwesomeValidationWithParams(3)],\n  });\n\n  // ... render logic errors here\n}\n```\n\n## Custom validation message\n\nIn some cases you need to render custom validation message for rule.\nYou can do it with helper function `customMessage`.\n\n`customMessage` receive validation message as first argument, rule as second.\n\n```tsx\nimport useValidator, { required, min customMessage } from 'use-validatorjs';\n\nfunction App() {\n  const data = {\n    some: '',\n    price: 3\n  };\n\n  const { isErrors, errors } = useValidator(t, data, {\n    some: customMessage('This is very important field', required),\n    price: customMessage('Price field should be as least 6', min(6))\n  });\n\n  // ... render logic errors here\n}\n```\n\n## i18n\n\nTypically in semi-size apps we already have some i18n engine.\nIn this case synchronize language output from a lot of libraries really painful.\nFor example: we have i18next as base engine, moment.js for date view, data-validation with own interpolation dialect, some ui-component library with included texts for close buttons of modals.\nTo reach consistent translation of app we should sync all of these libs on several lifecycles and cases:\n\n- at app loading phase - there is no seanse to download all langs on app startup\n- change language - all libs should pre-load it's translation and call change current language at one moment\n- sync translation files - should remebemer all interpolation dialects (sometimes it is `{{}}`, sometimes it is `:value:`) and don't miss to add new lang for your libs\n- undestanding how to change whole translation file for some of libs - sometimes texts too casual for your ui\n\nWe faced with this problem too often. So, `useValidation` don't use own translation engine under the hood.\nIt receive translation function as first argument. Function should have compatible interface with [t from react-i18next](https://www.i18next.com/overview/api#t) or [t from i18n-lite](https://github.com/zamarawka/i18n-lite#t). If you use one of this libs you could simply pass this function with binded namespace:\n\n```tsx\nimport useValidator, { required, min customMessage } from 'use-validatorjs';\nimport { useTranslation } from 'i18n-lite';\n\nfunction App() {\n  const { t: validationT } = useTranslation('validation');\n  const data = {\n    some: '',\n    price: 3\n  };\n\n  const { isErrors, errors } = useValidator(validationT, data, {\n    some: customMessage(validationT('custom.required.key'), required),\n    price: min(6)\n  });\n\n  // ... render logic errors here\n}\n```\n\nIn other cases it is up to you create your own implementation according with your environment.\n\nBad news: at this moment there are no out of the box translation files for rules. It is under development and will appear as soon as possible.\n\n## Rules\n\n### required\n\nCheck value is required\n\n```tsx\n// Negative cases\nconst data = {\n  num: NaN,\n  str: '',\n  bool: false,\n};\n\n// Positive cases\nconst data = {\n  num: 0,\n  str: 'any not empty string',\n  bool: true,\n};\n\n// Example\nconst rules = {\n  num: required,\n  str: required,\n  bool: required,\n};\n```\n\n### requiredIf\n\nCheck value required if other value equals\n\n```tsx\n// Negative cases\nconst data = {\n  other: 3,\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 3,\n  some: true,\n};\n\nconst data = {\n  other: 5,\n  some: true,\n};\n\n// Example\nconst rules = {\n  some: requiredIf(data.other, 3),\n};\n```\n\n### requiredUnless\n\nCheck value required if other value not equals\n\n```tsx\n// Negative cases\nconst data = {\n  other: 5,\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 3,\n  some: false,\n};\n\nconst data = {\n  other: 5,\n  some: true,\n};\n\n// Example\nconst rules = {\n  some: requiredUnless(data.other, 3),\n};\n```\n\n### requiredWith\n\nCheck value required if other value is positive\n\n```tsx\n// Negative cases\nconst data = {\n  other: 1,\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 1,\n  some: true,\n};\n\nconst data = {\n  other: 0,\n  some: false,\n};\n\n// Example\nconst rules = {\n  some: requiredWith(data.other),\n};\n```\n\n### requiredWithAll\n\nCheck value required if every of other values are positive\n\n```tsx\n// Negative cases\nconst data = {\n  other: 1,\n  foo: 'some',\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 1,\n  foo: 'some',\n  some: true,\n};\n\nconst data = {\n  other: 0,\n  foo: 'some', // or ''\n  some: false,\n};\n\n// Example\nconst rules = {\n  some: requiredWithAll([data.other, data.foo, true]),\n};\n```\n\n### requiredWithout\n\nCheck value required if other value is negative\n\n```tsx\n// Negative cases\nconst data = {\n  other: 0,\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 0,\n  some: true,\n};\n\nconst data = {\n  other: 1,\n  some: false,\n};\n\n// Example\nconst rules = {\n  some: requiredWithout(data.other),\n};\n```\n\n### requiredWithoutAll\n\nCheck value required if every of other values are negative\n\n```tsx\n// Negative cases\nconst data = {\n  other: 0,\n  foo: '',\n  some: false,\n};\n\n// Positive cases\nconst data = {\n  other: 0,\n  foo: '',\n  some: true,\n};\n\nconst data = {\n  other: 0, // or 1\n  foo: 'some',\n  some: false,\n};\n\n// Example\nconst rules = {\n  some: requiredWithoutAll([data.other, data.foo, false]),\n};\n```\n\n### same\n\nCheck value are same\n\n```tsx\n// Negative cases\nconst data = {\n  some: 5,\n  other: 'foo',\n};\n\n// Positive cases\nconst data = {\n  some: 3,\n  other: 'str',\n};\n\n// Example\nconst rules = {\n  some: same(3),\n  some: same('str'),\n};\n```\n\n### different\n\nCheck value are different\n\n```tsx\n// Negative cases\nconst data = {\n  some: 3,\n  other: 'str',\n};\n\n// Positive cases\nconst data = {\n  some: 5,\n  other: 'foo',\n};\n\n// Example\nconst rules = {\n  some: different(3),\n  some: different('str'),\n};\n```\n\n### min\n\nCheck value more than\n\n```tsx\n// Negative cases\nconst data = {\n  some: 2,\n};\n\n// Positive cases\nconst data = {\n  some: 5,\n};\n\n// Example\nconst rules = {\n  some: min(3),\n};\n```\n\n### max\n\nCheck value less than\n\n```tsx\n// Negative cases\nconst data = {\n  some: 5,\n};\n\n// Positive cases\nconst data = {\n  some: 2,\n};\n\n// Example\nconst rules = {\n  some: max(3),\n};\n```\n\n### minLength\n\nCheck value length less than\n\n```tsx\n// Negative cases\nconst data = {\n  someString: '12',\n  someArr: [1, 2],\n};\n\n// Positive cases\nconst data = {\n  someString: '1234',\n  someArr: [1, 2, 3, 4],\n};\n\n// Example\nconst rules = {\n  someString: minLength(3),\n  someArr: minLength(3),\n};\n```\n\n### maxLength\n\nCheck value length more than\n\n```tsx\n// Negative cases\nconst data = {\n  someString: '1234',\n  someArr: [1, 2, 3, 4],\n};\n\n// Positive cases\nconst data = {\n  someString: '12',\n  someArr: [1, 2],\n};\n\n// Example\nconst rules = {\n  someString: maxLength(3),\n  someArr: maxLength(3),\n};\n```\n\n### email\n\nCheck value is valid email adress\n\n```tsx\n// Negative cases\nconst data = {\n  some: 'some-random-string',\n};\n\n// Positive cases\nconst data = {\n  some: 'some@example.com',\n};\n\n// Example\nconst rules = {\n  some: email,\n};\n```\n\n### accepted\n\nCheck value is accepted. Typically checkboxes.\n\n```tsx\n// Negative cases\nconst data = {\n  some: 0,\n  other: false,\n};\n\n// Positive cases\nconst data = {\n  some: 1,\n  other: true,\n};\n\n// Example\nconst rules = {\n  some: accepted,\n};\n```\n\n# Development\n\n```sh\nnpm run format # code fomatting\nnpm run lint # linting\nnpm run test # testing\n```\n\nActive maintenance with care and ❤️.\n\nFeel free to send a PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamarawka%2Fuse-validatorjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzamarawka%2Fuse-validatorjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamarawka%2Fuse-validatorjs/lists"}