React primitives for building credit card components
npm install react-credit-card-primitives-upd> React primitives to build a credit card form. 7kb gzipped.
Relies on the creditcards library. Inspired by @bendrucker's virtual-credit-cards.
``
$ npm install --save react-credit-card-primitives
When you need to build a credit card form, it's really hard to find something that is:
- Small bundle size
- Customizable
- Doesn't come with loads of CSS that you don't want to use.
Often when building a custom credit card form, all you want is the building blocks. This library provides those using the "bring your own render" philosophy, using prop getters to hand you properties to put on your own elements to render the form.
`jsx`
import {Number, Cvc, Expiration} from 'react-credit-card-primitives'
ReactDOM.render(
,
render={({
getInputProps,
valid
}) => } />
render={({
getInputProps,
valid,
error
}) => (
{!value ? ''
: error === Expiration.ERROR_MONTHYEAR ? 'Please enter valid month and year'
: error === Expiration.ERROR_MONTH ? 'Please enter valid month'
: error === Expiration.ERROR_YEAR ? 'Please enter valid year'
: error === Expiration.ERROR_PAST_DATE ? 'Please enter a date in the future.'
: ''}
)} />
render={({
getInputProps,
valid
}) => } />
/>
document.body
)
Create a credit card input that formats the user's input with spaces every four digits. Formats and validates user input with creditcards.card.
`js`
import {Number} from 'react-credit-card-primitives'
// OR:
import Number from 'react-credit-card-primitives/number'
#### Props
#### value
> string | optional
The credit card number without spaces (eg 4242424242424242). The non-formatted version of the user input.
If not provided, the Number component will manage its value via internal state (it will be an "uncontrolled component").
If value is provided, the Number component becomes a "controlled component".
The onChange prop is called whenever value changes.
#### defaultValue
> string | optional
If no value is provided, this will set the initial value.
#### onChange
> function(object: NumberStateAndHelpers) | optional
Called when the value changes. NumberStateAndHelpers is the same object received by the render prop function.
#### masked
> boolean | optional
If true, when a valid credit card number is typed and the input is not focused, the input will be masked.
All but the last 4 digits of the credit card number will be replaced with •.
Use the getMaskedValue(object: NumberStateAndHelpers): rawValue prop to customize the masked value.
The default behavior is as follows. Given the following markup, the input will have the value '•••• •••• •••• 4242':
#### cardTypes
> Array | optional
Example:
The given types, if provided, will be the only allowed credit card types.
By default, all card types are allowed.
#### render
> function(object: NumberStateAndHelpers) | required
Use the render prop function to render your number input and any associated elements (e.g. an image representing the current card type or any errors).
The render prop function is called with the following NumberStateAndHelpers object:
| property | category | type | description |
|---------------|-------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| value | state | string | The currently entered credit card number (without spaces or formatting) |
| valid | state | boolean | Whether the given value is a valid credit card number (via creditcards.card.isValid. If the cardTypes property is passed in, this says whether the value is a valid version of one of those card types. |'Visa'
| type | state | string | What credit card type the currently entered number is (eg ). |
| getInputProps | prop getter | function | The properties to put on your element. |
| getLabelProps | prop getter | function | The properties to put on your
> creditcards instance | optional, default is require('creditcards')
A creditcards instance with custom types, constructed using creditcards.withTypes().
Create an expiration input that automatically puts a separator ( / ) between month and year. Formats and validates user input with creditcards.expiration.
Provides you with parsed month and year as numbers.
`js`
import {Expiration} from 'react-credit-card-primitives'
// OR:
import Expiration from 'react-credit-card-primitives/expiration'
#### Props
#### month
> number | optional
The entered month, 1-12.
If not provided, the Expiration component will manage its month via internal state (uncontrolled).
If provided, it must be provided with the year prop.
The onChange prop is called whenever month changes.
#### year
> number | optional
The entered year, four digits.
If not provided, the Expiration component will manage its year via internal state.
If provided, it must be provided with the month prop.
The onChange prop is called whenever year changes.
#### defaultMonth
> number | optional
If no month is provided, this will set the initial month.
#### defaultYear
> number | optional
If no year is provided, this will set the initial year.
#### onChange
> function(object: ExpirationStateAndHelpers)
Called when the month or year changes. ExpirationStateAndHelpers is the same object received by the render prop function.
#### render
> function(object: ExpirationStateAndHelpers) | required
Use the render prop function to render your expiration input and any associated elements (e.g. errors).
The render prop function is called with the following ExpirationStateAndHelpers object:
| property | category | type | description |
|---------------|-------------|----------|---------------------------------------------------------------|
| month | state | number | The currently entered month or undefined. |
| year | state | number | The currently entered four-digit year or undefined. |
| rawValue | state | string | The value currently entered into the input (e.g. '11 / 19' |Errors
| error | state | string | The current error, if input is not valid. See below. |
| valid | state | boolean | Whether the input is currently a valid month/year. |
| getInputProps | prop getter | function | The properties to put on your element. |
| getLabelProps | prop getter | function | The properties to put on your
> creditcards instance | optional, default is require('creditcards')
A creditcards instance with custom types, constructed using creditcards.withTypes(). |
#### Errors
The possible values for error in ExpirationStateAndHelpers. These are provided because expiration errors can be of several different types. Use these to display errors in your UI:
- Expiration.ERROR_MONTH_YEAR ('err_monthyear')Expiration.ERROR_MONTH
- ('err_month')Expiration.ERROR_YEAR
- ('err_year')Expiration.ERROR_PAST_DATE
- ('err_pastdate')
Create a cvc input. Validates user input with creditcards.cvc.
`js`
import {Cvc} from 'react-credit-card-primitives'
// OR:
import Cvc from 'react-credit-card-primitives/cvc'
#### Props
#### value
> string | optional
The entered cvc number.
If not provided, the Cvc component will manage its value via internal state (uncontrolled component).
If value is provided, the Cvc component becomes a "controlled component".
The onChange prop is called whenever value changes.
#### defaultValue
> string | optional
If no value is provided, this will set the initial value.
#### masked
> boolean | optional
If true, the input's value will be replaced with • while blurred.
#### cardType
> string
By default, the cvc input will be validated as needing to be of length 3 or 4.
If a type id is given, the cvc input must match the length of the given type.
For example, the following will validate the length as 4 for american express cards:
`js`
#### onChange
> function(object: CvcStateAndHelpers) | optional
Called when the value changes. CvcStateAndHelpers is the same object received by the render prop function.
#### render
> function(object: CvcStateAndHelpers) | required
Use the render prop function to render your cvc input and any associated elements (e.g. errors).
The render prop function is called with the following CvcStateAndHelpers object:
| property | category | type | description |
|---------------|-------------|----------|--------------------------------------------------------------------------------------------------------|
| value | state | string | The currently entered cvc code |
| focused | state | boolean | Whether the cvc input is focused |
| valid | state | boolean | Whether the cvc input is valid. If cardType is provided, the cvc is validated against that cardType. |
| getInputProps | prop getter | function | The properties to put on your element. |
| getLabelProps | prop getter | function | The properties to put on your
> creditcards instance` | optional, default is require('creditcards')
A creditcards instance with custom types, constructed using creditcards.withTypes().
MIT © Andrew Joslin