React Payment Inputs

> A React Hook & Container to help with payment card input fields.

- React Payment Inputs
- Demos
- Requirements
- Installation
- Usage
- With hooks
- With render props
- Using the built-in styled wrapper
- More examples
- data = usePaymentInputs(options)
- options
- options.cardNumberValidator
- Example
- options.cvcValidator
- options.errorMessages
- Example
- options.expiryDateValidator
- options.onBlur
- options.onChange
- options.onError
- options.onTouch
- data
- getCardNumberProps
- Example snippet
- getExpiryDateProps
- Example snippet
- getCVCProps
- Example snippet
- getZIPProps
- Example snippet
- getCardImageProps
- Example snippet
- meta.cardType
- Example snippet
- meta.error
- Example snippet
- meta.isTouched
- meta.erroredInputs
- Example snippet
- meta.touchedInputs
- Example snippet
- meta.focused
- wrapperProps
- props
- styles
- Schema
- errorTextProps
- inputWrapperProps
- Using a third-party UI library
- Fannypack
- Bootstrap
- Form library examples
- Formik
- React Final Form
- Customising the in-built style wrapper
- Custom card images
- License

Demos

Requirements

Ensure you are running on a hooks-compatible version of React (v16.8 & above).

Installation

``
npm install react-payment-inputs --save
`

or install with Yarn if you prefer:

`
yarn add react-payment-inputs
`

Usage

By default (as seen above), React Payment Inputs does not come with built-in styling meaning that you can easily adapt React Payment Inputs to your own design system.

However, if you would like to use the built-in styles as seen in the animation above, read "Using the built-in styled wrapper".

$3

If you'd like to use the hooks version of React Payment Inputs, you can import usePaymentInputs into your component.

`jsx
import React from 'react';
import { usePaymentInputs } from 'react-payment-inputs';

export default function PaymentInputs() {
const { meta, getCardNumberProps, getExpiryDateProps, getCVCProps } = usePaymentInputs();

return (


> By spreading the prop getter functions (e.g. {...getCardNumberProps()}) on the inputs as shown above, React Payment Inputs will automatically handle the formatting, focus & validation logic for you.

> IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the prop getter function (e.g. getCardNumberProps()) so the default event handlers in React Payment Inputs don't get overridden.

$3

If you'd like to use the render props version of React Payment Inputs, you can import PaymentInputsContainer into your component.

The props of are the same as the hook options and the render props are the same as the hook data.

`jsx
import React from 'react';
import { PaymentInputsContainer } from 'react-payment-inputs';

export default function PaymentInputs() {
return (

{({ meta, getCardNumberProps, getExpiryDateProps, getCVCProps }) => (


> IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the prop getter function (e.g. getCardNumberProps()) so the default event handlers in React Payment Inputs don't get overridden.

$3

> Note: requires styled-components to be installed as a dependency.

By default, React Payment Inputs does not have built-in styling for it's inputs. However, React Payment Inputs comes with a styled wrapper which combines the card number, expiry & CVC fields seen below:

`jsx
import React from 'react';
import { PaymentInputsWrapper, usePaymentInputs } from 'react-payment-inputs';
import images from 'react-payment-inputs/images';

export default function PaymentInputs() {
const {
wrapperProps,
getCardImageProps,
getCardNumberProps,
getExpiryDateProps,
getCVCProps
} = usePaymentInputs();

return (






);
}
`

$3

- Storybook
- Source

data = usePaymentInputs(options)

> returns an object (data)

$3

> Object({ cardNumberValidator, cvcValidator, errorMessages, expiryValidator, onBlur, onChange, onError, onTouch })

#### options.cardNumberValidator
> function({cardNumber, cardType, errorMessages})

Set custom card number validator function

##### Example

`js
const cardNumberValidator = ({ cardNumber, cardType, errorMessages }) => {
if (cardType.displayName === 'Visa' || cardType.displayName === 'Mastercard') {
return;
}
return 'Card must be Visa or Mastercard';
}

export default function MyComponent() {
const { ... } = usePaymentInputs({
cardNumberValidator
});
}
`

#### options.cvcValidator
> function({cvc, cardType, errorMessages})

Set custom cvc validator function


#### options.errorMessages

> Object

Set custom error messages for the inputs.

##### Example

`js
const ERROR_MESSAGES = {
emptyCardNumber: 'El número de la tarjeta es inválido',
invalidCardNumber: 'El número de la tarjeta es inválido',
emptyExpiryDate: 'La fecha de expiración es inválida',
monthOutOfRange: 'El mes de expiración debe estar entre 01 y 12',
yearOutOfRange: 'El año de expiración no puede estar en el pasado',
dateOutOfRange: 'La fecha de expiración no puede estar en el pasado',
invalidExpiryDate: 'La fecha de expiración es inválida',
emptyCVC: 'El código de seguridad es inválido',
invalidCVC: 'El código de seguridad es inválido'
}

export default function MyComponent() {
const { ... } = usePaymentInputs({
errorMessages: ERROR_MESSAGES
});
}
`

#### options.expiryDateValidator
> function({expiryDate, errorMessages})

Set custom expiry date validator function


#### options.onBlur

> function(event)

Function to handle the blur event on the inputs. It is invoked when any of the inputs blur.

#### options.onChange

> function(event)

Function to handle the change event on the inputs. It is invoked when any of the inputs change.

#### options.onError

> function(error, erroredInputs)

Function to invoke when any of the inputs error.

#### options.onTouch

> function(touchedInput, touchedInputs)

Function to invoke when any of the inputs are touched.

$3

#### getCardNumberProps

> function(overrideProps) | returns Object

Returns the props to apply to the card number input.

IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the getCardNumberProps() so the default event handlers in React Payment Inputs don't get overridden.

##### Example snippet

`jsx

`

#### getExpiryDateProps

> function(overrideProps) | returns Object

Returns the props to apply to the expiry date input.

IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the getExpiryDateProps() so the default event handlers in React Payment Inputs don't get overridden.

##### Example snippet

`jsx

`

#### getCVCProps

> function(overrideProps) | returns Object

Returns the props to apply to the CVC input.

IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the getCVCProps() so the default event handlers in React Payment Inputs don't get overridden.

##### Example snippet

`jsx

`

#### getZIPProps

> function(overrideProps) | returns Object

Returns the props to apply to the ZIP input.

IMPORTANT: You must place your event handlers (e.g. onChange, onBlur, etc) inside the getZIPProps() so the default event handlers in React Payment Inputs don't get overridden.

##### Example snippet

`jsx

`

#### getCardImageProps

> function({ images }) | returns Object

Returns the props to apply to the card image SVG.

This function only supports SVG elements currently. If you have a need for another format, please raise an issue.

You can also supply custom card images using the images attribute. The example below uses the default card images from React Payment Inputs.

##### Example snippet

`jsx
import images from 'react-payment-inputs/images';


`

#### meta.cardType

> Object

Returns information about the current card type, including: name, lengths and formats.

##### Example snippet

`jsx
const { meta } = usePaymentInputs();

Current card: {meta.cardType.displayName}
`

#### meta.error

> string

Returns the current global error between all rendered inputs.

##### Example snippet

`jsx
const { meta } = usePaymentInputs();

console.log(meta.error); // "Card number is invalid"
`

#### meta.isTouched

> boolean

Returns the current global touched state between all rendered inputs.

#### meta.erroredInputs

> Object

Returns the error message of each rendered input.

##### Example snippet

`jsx
const { meta } = usePaymentInputs();

console.log(meta.erroredInputs);
/*
{
cardNumber: undefined,
expiryDate: 'Enter an expiry date',
cvc: 'Enter a CVC'
}
*/
`

#### meta.touchedInputs

> Object

Returns the touch state of each rendered input.

##### Example snippet

`jsx
const { meta } = usePaymentInputs();

console.log(meta.touchedInputs);
/*
{
cardNumber: true,
expiryDate: true,
cvc: false
}
*/
`

#### meta.focused

> string

Returns the current focused input.

`jsx
const { meta } = usePaymentInputs();

console.log(meta.focused); // "cardNumber"
`

#### wrapperProps

> Object

Returns the props to apply to .

props

$3

> Object

Custom styling to pass through to the wrapper. Either a styled-component's css or an Object can be passed.

#### Schema

`
{
fieldWrapper: {
base: css | Object,
errored: css | Object
},
inputWrapper: {
base: css | Object,
errored: css | Object,
focused: css | Object
},
input: {
base: css | Object,
errored: css | Object,
cardNumber: css | Object,
expiryDate: css | Object,
cvc: css | Object
},
errorText: {
base: css | Object
}
}
`

$3

> Object

Custom props to pass to the error text component.

$3

> Object

Custom props to pass to the input wrapper component.

Using a third-party UI library

React Payment Inputs allows you to integrate into pretty much any React UI library. Below are a couple of examples of how you can fit React Payment Inputs into a UI library using usePaymentInputs. You can also do the same with .

$3

`jsx
import React from 'react';
import { FieldSet, InputField } from 'fannypack';
import { usePaymentInputs } from 'react-payment-inputs';
import images from 'react-payment-inputs/images';

export default function PaymentInputs() {
const {
meta,
getCardNumberProps,
getExpiryDateProps,
getCVCProps
} = usePaymentInputs();
const { erroredInputs, touchedInputs } = meta;

return (


`jsx
import React from 'react';
import { FieldSet, InputField } from 'fannypack';
import { usePaymentInputs } from 'react-payment-inputs';
import images from 'react-payment-inputs/images';

export default function PaymentInputs() {
const {
meta,
getCardNumberProps,
getExpiryDateProps,
getCVCProps
} = usePaymentInputs();
const { erroredInputs, touchedInputs } = meta;

return (


`jsx
import { Formik, Field } from 'formik';
import { PaymentInputsWrapper, usePaymentInputs } from 'react-payment-inputs';

function PaymentForm() {
const {
meta,
getCardImageProps,
getCardNumberProps,
getExpiryDateProps,
getCVCProps,
wrapperProps
} = usePaymentInputs();

return (
initialValues={{
cardNumber: '',
expiryDate: '',
cvc: ''
}}
onSubmit={data => console.log(data)}
validate={() => {
let errors = {};
if (meta.erroredInputs.cardNumber) {
errors.cardNumber = meta.erroredInputs.cardNumber;
}
if (meta.erroredInputs.expiryDate) {
errors.expiryDate = meta.erroredInputs.expiryDate;
}
if (meta.erroredInputs.cvc) {
errors.cvc = meta.erroredInputs.cvc;
}
return errors;
}}
>
{({ handleSubmit }) => (


`jsx
import { Form, Field } from 'react-final-form';
import { PaymentInputsWrapper, usePaymentInputs } from 'react-payment-inputs';

function PaymentForm() {
const {
meta,
getCardImageProps,
getCardNumberProps,
getExpiryDateProps,
getCVCProps,
wrapperProps
} = usePaymentInputs();

return (
onSubmit={data => console.log(data)}
validate={() => {
let errors = {};
if (meta.erroredInputs.cardNumber) {
errors.cardNumber = meta.erroredInputs.cardNumber;
}
if (meta.erroredInputs.expiryDate) {
errors.expiryDate = meta.erroredInputs.expiryDate;
}
if (meta.erroredInputs.cvc) {
errors.cvc = meta.erroredInputs.cvc;
}
return errors;
}}
>
{({ handleSubmit }) => (


React Payment Input's default style wrapper can be customized by supplying a styles prop.

`jsx
import { css } from 'styled-components';
import { usePaymentInputs, PaymentInputsWrapper } from 'react-payment-inputs';

function PaymentForm() {
const {
getCardNumberProps,
getExpiryDateProps,
getCVCProps,
wrapperProps
} = usePaymentInputs();

return (
{...wrapperProps}
styles={{
fieldWrapper: {
base: css
margin-bottom: 1rem;

},
inputWrapper: {
base: css
border-color: green;
,
errored: css
border-color: maroon;
,
focused: css
border-color: unset;
box-shadow: unset;
outline: 2px solid blue;
outline-offset: 2px;

},
input: {
base: css
color: green;
,
errored: css
color: maroon;
,
cardNumber: css
width: 15rem;
,
expiryDate: css
width: 10rem;
,
cvc: css
width: 5rem;

},
errorText: {
base: css
color: maroon;

}
}}
>




);
}
`

See the example on Storybook

Custom card images

The card images can be customized by passing the images attribute to getCardImageProps({ images }). The images object must consist of SVG paths.

`jsx
import { css } from 'styled-components';
import { usePaymentInputs, PaymentInputsWrapper } from 'react-payment-inputs';

const images = {
mastercard: (




d="m12 3.99963381c1.2144467.91220633 2 2.36454836 2 4.00036619s-.7855533 3.0881599-2 4.0003662c-1.2144467-.9122063-2-2.36454837-2-4.0003662s.7855533-3.08815986 2-4.00036619z"
fill="#ff5f00"
/>

)
}

function PaymentForm() {
const {
getCardNumberProps,
getExpiryDateProps,
getCVCProps,
getCardImageProps,
wrapperProps
} = usePaymentInputs();

return (






);
}
``

License

MIT © Medipass Solutions Pty. Ltd.