@dhis2/prop-types

DHIS2 propTypes

This package contains common prop types used across dhis2 apps and libraries.

Installation

yarn add @dhis2/prop-types

Available prop-types

Functions

arrayWithLength([min], [max], [propType]) ⇒ Error | null

Ensure the prop value is an array with a length between a minimum and maximum. If a third propType argument is passed each item in the array needs to be of that prop-type

instanceOfComponent(Component) ⇒ Error | null

Ensure the prop value is an instance of a certain component

mutuallyExclusive(exlusivePropNames, propType) ⇒ Error | null

Ensure that only one property within a specified list is thruthy This function will also check if the current property value is of the specified type

requiredIf(siblingPropName) ⇒ Error | null

Ensure the prop has a value (i.e. treat it as required) when a given sibling prop also has a value, and ensure the prop is of the correct prop-type

arrayWithLength([min], [max], [propType]) ⇒ Error | null

Ensure the prop value is an array with a length between a minimum and maximum. If a third propType argument is passed each item in the array needs to be of that prop-type

Kind: global function
Returns: Error | null - Returns null if all conditions are met, or an error

Param	Type	Default	Description
[min]	number	0	The minimal array length
[max]	number	Infinity	The maximal array length
[propType]	function		The prop-type that each array item needs to conform to

Example

import React from 'react'
import { arrayWithLength } from '@dhis2/prop-types'

const LotsOfLists = props => <div {...props}>Does nothing</div>

LotsOfLists.propTypes = {
    arrayWithMaxThreeNumbers: arrayWithLength(0, 3, propTypes.number),
    arrayWithAtLeastSixStrings: arrayWithLength(6, undefined, propTypes.string),
    arrayWithAtLeastTenItems: arrayWithLength(10),
    mandatoryArrayBetweenOneAndTen: arrayWithLength(1,10).isRequired,
}

instanceOfComponent(Component) ⇒ Error | null

Ensure the prop value is an instance of a certain component

Kind: global function
Returns: Error | null - Returns null if all conditions are met, or an error

Param	Type	Description
Component	function | string	The component that is expected. Can either be a React component, or a string for built-in components, such as 'span', 'div', etc.

Example

import React from 'react'
import { instanceOfComponent } from '@dhis2/prop-types'
import { Button } from './Button'

const ButtonWrap = ({ children }) => <div>{children}</div>
// This would allow the ButtonWrap to be empty
ButtonWrap.propTypes = {
    children: instanceOfComponent(Button)
}

// Enforce presence of a Button instance
ButtonWrap.propTypes = {
    children: instanceOfComponent(Button).isRequired
}

// Enforce presence of a multiple children, all Button instances
ButtonWrap.propTypes = {
    children: proptypes.arrayOf(instanceOfComponent(Button)).isRequired
}

mutuallyExclusive(exlusivePropNames, propType) ⇒ Error | null

Ensure that only one property within a specified list is thruthy This function will also check if the current property value is of the specified type

Kind: global function
Returns: Error | null - Returns null if all conditions are met, or an error

Param	Type	Description
exlusivePropNames	array.<string>	The prop names to be checked
propType	function	The prop-type that the current prop-value needs to conform to

Example

import React from 'react'
import cx from 'classnames'
import propTypes from 'prop-types'
import { mutuallyExclusive } from '@dhis2/prop-types'

const Alert = ({ danger, warning, success, children }) => (
    <div className={cx({danger, warning, success})}>
        {children}
    </div>
)

const statusPropType = mutuallyExclusive(['danger', 'warning', 'success'], propTypes.bool)

Alert.propTypes = {
    children: propTypes.node,
    danger: statusPropType,
    warning: statusPropType,
    success: statusPropType,
}

requiredIf(siblingPropName) ⇒ Error | null

Ensure the prop has a value (i.e. treat it as required) when a given sibling prop also has a value, and ensure the prop is of the correct prop-type

Kind: global function
Returns: Error | null - Returns null if all conditions are met, or an error

Param	Type	Description
siblingPropName	function	The name of the sibling prop

Example

import React from 'react'
import { requiredIf } from '@dhis2/prop-types'

const Test = ({ someBool, someString }) => (
    <div>
        <h1>someBool: {someBool ? 'true' : 'false'}</h1>
        <h1>someString: {someString}</h1>
    </div>
)
Test.propTypes = {
    someBool: propTypes.bool,
    someString: requiredIf(props => props.someBool, propTypes.string),
}

Changelog

1.5.0 (2019-12-04)

Bug Fixes

• array with length: check prop type correctly & fix error message (c465743)
• required if: remove duplicate prop name from error message (f9f44b0)

Features

• instance of component: display name instead of the function body (ede4312)