{"id":19004878,"url":"https://github.com/dhis2/prop-types","last_synced_at":"2025-04-22T18:49:27.981Z","repository":{"id":35017771,"uuid":"191575246","full_name":"dhis2/prop-types","owner":"dhis2","description":"Common prop types used across DHIS 2 apps and libraries","archived":false,"fork":false,"pushed_at":"2023-03-06T13:58:57.000Z","size":4004,"stargazers_count":2,"open_issues_count":17,"forks_count":1,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-03-29T17:51:07.249Z","etag":null,"topics":["synced-settings","web-lib"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhis2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2019-06-12T13:21:29.000Z","updated_at":"2021-09-30T08:38:11.000Z","dependencies_parsed_at":"2024-06-18T23:59:53.564Z","dependency_job_id":"15c41fe0-2d0a-4d7d-b617-0313ed1adbc4","html_url":"https://github.com/dhis2/prop-types","commit_stats":{"total_commits":168,"total_committers":13,"mean_commits":"12.923076923076923","dds":0.6607142857142857,"last_synced_commit":"45485ceabf7e4d8e814248f3afb32e75302d5cc9"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fprop-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fprop-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fprop-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fprop-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhis2","download_url":"https://codeload.github.com/dhis2/prop-types/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249037107,"owners_count":21202431,"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":["synced-settings","web-lib"],"created_at":"2024-11-08T18:25:03.452Z","updated_at":"2025-04-16T23:32:06.078Z","avatar_url":"https://github.com/dhis2.png","language":"JavaScript","readme":"# DHIS2 propTypes\n\nThis package contains common prop types used across dhis2 apps and libraries.\n\n## Installation\n\n```bash\nyarn add @dhis2/prop-types\n```\n\n## Available prop-types\n\n## Functions\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ca href=\"#arrayWithLength\"\u003earrayWithLength([min], [max], [propType])\u003c/a\u003e ⇒ \u003ccode\u003eError\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eEnsure the prop value is an array with a length between a minimum and maximum.\nIf a third \u003ccode\u003epropType\u003c/code\u003e argument is passed each item in the array needs to be of that prop-type\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#conditional\"\u003econditional(propsToPropType)\u003c/a\u003e ⇒ \u003ccode\u003eError\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eConditionally determines a prop type bases on the passed props\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#instanceOfComponent\"\u003einstanceOfComponent(Component)\u003c/a\u003e ⇒ \u003ccode\u003eError\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eEnsure the prop value is an instance of a certain component\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#mutuallyExclusive\"\u003emutuallyExclusive(exlusivePropNames, propType)\u003c/a\u003e ⇒ \u003ccode\u003eError\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eEnsure that only one property within a specified list is thruthy\nThis function will also check if the current property value is of the specified type\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#requiredIf\"\u003erequiredIf(siblingPropName)\u003c/a\u003e ⇒ \u003ccode\u003eError\u003c/code\u003e | \u003ccode\u003enull\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eEnsure the prop has a value (i.e. treat it as required) when a given sibling prop\nalso has a value, and ensure the prop is of the correct prop-type\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003ca name=\"arrayWithLength\"\u003e\u003c/a\u003e\n\n## arrayWithLength([min], [max], [propType]) ⇒ \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e\n\nEnsure the prop value is an array with a length between a minimum and maximum.\nIf a third `propType` argument is passed each item in the array needs to be of that prop-type\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e - Returns null if all conditions are met, or an error\n\n| Param      | Type                  | Default               | Description                                            |\n| ---------- | --------------------- | --------------------- | ------------------------------------------------------ |\n| [min]      | \u003ccode\u003enumber\u003c/code\u003e   | \u003ccode\u003e0\u003c/code\u003e        | The minimal array length                               |\n| [max]      | \u003ccode\u003enumber\u003c/code\u003e   | \u003ccode\u003eInfinity\u003c/code\u003e | The maximal array length                               |\n| [propType] | \u003ccode\u003efunction\u003c/code\u003e |                       | The prop-type that each array item needs to conform to |\n\n**Example**\n\n```js\nimport React from 'react'\nimport { arrayWithLength } from '@dhis2/prop-types'\n\nconst LotsOfLists = (props) =\u003e \u003cdiv {...props}\u003eDoes nothing\u003c/div\u003e\n\nLotsOfLists.propTypes = {\n    arrayWithMaxThreeNumbers: arrayWithLength(0, 3, propTypes.number),\n    arrayWithAtLeastSixStrings: arrayWithLength(6, undefined, propTypes.string),\n    arrayWithAtLeastTenItems: arrayWithLength(10),\n    mandatoryArrayBetweenOneAndTen: arrayWithLength(1, 10).isRequired,\n}\n```\n\n\u003ca name=\"conditional\"\u003e\u003c/a\u003e\n\n## conditional(propsToPropTypes) ⇒ \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e\n\nDetermine the prop type of a prop by the value(s) of a/several passed prop(s).\nThis will restrict the propType in contrast to `oneOfType`.\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e - Returns null if all conditions are met, or an error\n\n| Param           | Type                  | Default | Description                                           |\n| --------------- | --------------------- | ------- | ----------------------------------------------------- |\n| propsToPropType | \u003ccode\u003eFunction\u003c/code\u003e |         | The function that will determine the actual prop type |\n\n**Example**\n\n```js\nimport React from 'react'\nimport { conditional } from '@dhis2/prop-types'\n\nconst Select = ({ multiple, selected: _selected, options }) =\u003e {\n    const selected = multiple ? _selected : [ _selected ]\n\n    return (\n        // ...\n    )\n}\n\nconst option = propTypes.shape({\n    value: propTypes.string.isReuqired,\n    labe: propTypes.string.isReuqired,\n})\n\nLotsOfLists.propTypes = {\n    // ...\n    options: propTypes.arrayOf(option).isRequired,\n    selected: conditional(\n        props =\u003e props.multiple ? propTypes.arrayOf(option) : option\n    ).isRequired,\n    // ...\n}\n```\n\n\u003ca name=\"instanceOfComponent\"\u003e\u003c/a\u003e\n\n## instanceOfComponent(Component) ⇒ \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e\n\nEnsure the prop value is an instance of a certain component\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e - Returns null if all conditions are met, or an error\n\n| Param     | Type                                         | Description                                                                                                                       |\n| --------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| Component | \u003ccode\u003efunction\u003c/code\u003e \\| \u003ccode\u003estring\u003c/code\u003e | The component that is expected. Can either be a React component, or a string for built-in components, such as 'span', 'div', etc. |\n\n**Example**\n\n```js\nimport React from 'react'\nimport { instanceOfComponent } from '@dhis2/prop-types'\nimport { Button } from './Button'\n\nconst ButtonWrap = ({ children }) =\u003e \u003cdiv\u003e{children}\u003c/div\u003e\n// This would allow the ButtonWrap to be empty\nButtonWrap.propTypes = {\n    children: instanceOfComponent(Button),\n}\n\n// Enforce presence of a Button instance\nButtonWrap.propTypes = {\n    children: instanceOfComponent(Button).isRequired,\n}\n\n// Enforce presence of a multiple children, all Button instances\nButtonWrap.propTypes = {\n    children: proptypes.arrayOf(instanceOfComponent(Button)).isRequired,\n}\n```\n\n\u003ca name=\"mutuallyExclusive\"\u003e\u003c/a\u003e\n\n## mutuallyExclusive(exlusivePropNames, propType) ⇒ \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e\n\nEnsure that only one property within a specified list is thruthy\nThis function will also check if the current property value is of the specified type\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e - Returns null if all conditions are met, or an error\n\n| Param             | Type                              | Description                                                   |\n| ----------------- | --------------------------------- | ------------------------------------------------------------- |\n| exlusivePropNames | \u003ccode\u003earray.\u0026lt;string\u0026gt;\u003c/code\u003e | The prop names to be checked                                  |\n| propType          | \u003ccode\u003efunction\u003c/code\u003e             | The prop-type that the current prop-value needs to conform to |\n\n**Example**\n\n```js\nimport React from 'react'\nimport cx from 'classnames'\nimport propTypes from 'prop-types'\nimport { mutuallyExclusive } from '@dhis2/prop-types'\n\nconst Alert = ({ danger, warning, success, children }) =\u003e (\n    \u003cdiv className={cx({ danger, warning, success })}\u003e{children}\u003c/div\u003e\n)\n\nconst statusPropType = mutuallyExclusive(\n    ['danger', 'warning', 'success'],\n    propTypes.bool\n)\n\nAlert.propTypes = {\n    children: propTypes.node,\n    danger: statusPropType,\n    warning: statusPropType,\n    success: statusPropType,\n}\n```\n\n\u003ca name=\"requiredIf\"\u003e\u003c/a\u003e\n\n## requiredIf(siblingPropName) ⇒ \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e\n\nEnsure the prop has a value (i.e. treat it as required) when a given sibling prop\nalso has a value, and ensure the prop is of the correct prop-type\n\n**Kind**: global function  \n**Returns**: \u003ccode\u003eError\u003c/code\u003e \\| \u003ccode\u003enull\u003c/code\u003e - Returns null if all conditions are met, or an error\n\n| Param           | Type                  | Description                  |\n| --------------- | --------------------- | ---------------------------- |\n| siblingPropName | \u003ccode\u003efunction\u003c/code\u003e | The name of the sibling prop |\n\n**Example**\n\n```js\nimport React from 'react'\nimport { requiredIf } from '@dhis2/prop-types'\n\nconst Test = ({ someBool, someString }) =\u003e (\n    \u003cdiv\u003e\n        \u003ch1\u003esomeBool: {someBool ? 'true' : 'false'}\u003c/h1\u003e\n        \u003ch1\u003esomeString: {someString}\u003c/h1\u003e\n    \u003c/div\u003e\n)\nTest.propTypes = {\n    someBool: propTypes.bool,\n    someString: requiredIf((props) =\u003e props.someBool, propTypes.string),\n}\n```\n\n## Migrating to `@dhis2/prop-types` V3\n\n### Change summary\n\n`@dhis2/prop-types` previously had a direct dependency on the `prop-types` library and also re-exported its exports:\n\n-   In v1 we used to export a default object that included all of the regular prop-types and the DHIS2 custom prop-types. We also exposed all the regular and custom prop-types as named exports.\n-   In v2 we took a slightly different approach:\n    -   DHIS2 custom prop-types were available as named exports\n    -   The default export was an object containing all the custom prop-types\n    -   Regular prop-types were exported via the `PropTypes` export\n-   And now in v3 we do not re-export anything from the `prop-types` package anymore. Instead we simply expose our own custom prop-types functions as named exports.\n\n### Migrating from v1 to v3\n\nThese are the steps to take:\n\n1. Install version v3.0.0, for example by running `yarn upgrade @dhis2/prop-types --latest`. Ensure the `package.json` has an entry for `\"@dhis2/prop-types\": \"^3.x.x\"`\n1. Prepare the files for the new version by running the codemod provided with this release:\n    - Ensure a recent version of `@dhis2/cli` is installed.\n    - Ensure the codemod is available by running:\n        ```\n        d2 utils codemod list\n        ```\n        You should see `@dhis2/prop-types:prop-types-v1-v3.js` listed.\n    - Apply the codemod by running:\n        ```\n        d2 utils codemod apply @dhis2/prop-types:prop-types-v1-v3.js **/*.js`\n        ```\n1. Ensure the `prop-types` package is listed as a regular dependency in `package.json`.\n1. Scan the project for imports from `@dhis2/prop-types` (doing a global search for `from '@dhis2/prop-types'` will do the trick).\n    - If any of these imports are encountered, the project still needs this dependency.\n    - Quite likely, the search will yield no results, which means the `@dhis2/prop-types` dependency should be removed.\n\n### Migrating from v2 to v3\n\nNo codemod is available to transform the component files, but this should be fairly straightforward:\n\n1. Replace `import { PropTypes } from '@dhis2/prop-types'` with `import PropTypes from 'prop-types'`.\n1. The previous step should update most of the component files in the project correctly. If there are still component files left that import from `@dhis2/prop-types`, then probably these are actually using DHIS2 custom prop-types and these files should be addressed individually.\n\nOnce the component files have been updated, the dependencies in `package.json` need to be updated in eaxtly the same way as illustrated in step 3 and 4 of the v1 -\u003e 3 migration section.\n\n## Report an issue\n\nThe issue tracker can be found in [DHIS2 JIRA](https://jira.dhis2.org)\nunder the [LIBS](https://jira.dhis2.org/projects/LIBS) project.\n\nDeep links:\n\n-   [Bug](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10006\u0026components=11008)\n-   [Feature](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10300\u0026components=11008)\n-   [Task](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10003\u0026components=11008)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fprop-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhis2%2Fprop-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fprop-types/lists"}