Secure Fields UX options

Auto focus

Automatically focus a field when it loads by setting the autoFocus option to true. This is useful for focusing the card number field when the payment form first appears.

<CardNumber autoFocus />

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  autoFocus: true,
})

Only one field should have autoFocus enabled at a time.

Input masking

Mask the values in the card number and security code fields to hide sensitive data. Masking replaces digits with a special character (default •).

Mask on blur

By default, masking is applied when the field loses focus and removed when it regains focus.

<CardNumber maskInput />

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  maskInput: true,
})

To use a different masking character, pass an object with character:

<CardNumber
  maskInput={{
    character: '*',
  }}
/>

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  maskInput: {
    character: '*',
  },
})

Real-time masking

To mask the input as the user types, enable the maskOnInput option.

When real-time masking is enabled, each character is briefly shown in plain text as the user types it, then redacted after a short delay. This preview behavior is always on when using real-time masking and is not configurable.

<CardNumber
  maskInput={{
    character: '•',
    maskOnInput: true,
  }}
/>

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  maskInput: {
    character: '•',
    maskOnInput: true,
  },
})

Show last four digits

For card number fields, you can keep the last four digits visible when masking a valid card number by setting showLastFour to true.

<CardNumber
  maskInput={{
    character: '•',
    showLastFour: true,
  }}
/>

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  maskInput: {
    character: '•',
    showLastFour: true,
  },
})

The showLastFour option is only available on card number fields.

Mask input options

Option	Type	Default	Description
`character`	`string`	`•`	The character used to replace digits.
`showLastFour`	`boolean`	`false`	Keep the last four digits visible when the card number is valid. Only available on card number fields.
`maskOnInput`	`boolean`	`false`	Mask the input in real-time as the user types, instead of only on blur.

Programmatic masking

You can also mask and unmask a field programmatically using the redactValue() and unredactValue() methods. This lets you build a custom show/hide toggle.

import { useRef, useState } from 'react'
import { CardNumber } from '@gr4vy/secure-fields-react'

const MaskedCardNumber = () => {
  const cardNumberRef = useRef(null)
  const [isRedacted, setIsRedacted] = useState(false)

  const toggleMask = () => {
    if (isRedacted) {
      cardNumberRef.current?.unredactValue()
    } else {
      cardNumberRef.current?.redactValue()
    }
  }

  return (
    <>
      <CardNumber
        ref={cardNumberRef}
        maskInput
        onRedacted={() => setIsRedacted(true)}
        onUnredacted={() => setIsRedacted(false)}
      />
      <button type="button" onClick={toggleMask}>
        {isRedacted ? 'Show' : 'Hide'}
      </button>
    </>
  )
}

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  maskInput: true,
})

let isRedacted = false

cardNumberField.addEventListener('redacted', () => {
  isRedacted = true
})
cardNumberField.addEventListener('unredacted', () => {
  isRedacted = false
})

const toggleButton = document.querySelector('#toggle-mask')
toggleButton?.addEventListener('click', () => {
  if (isRedacted) {
    cardNumberField.unredactValue()
  } else {
    cardNumberField.redactValue()
  }
})

Auto advance

Automatically move focus to the next field when the current field’s value is complete and valid.

Auto advance is an opinionated pattern that may negatively affect the user experience, especially for users who edit fields out of order or use assistive technologies. Consider carefully whether this feature suits your needs.

<SecureFields
  gr4vyId="example"
  environment="sandbox"
  sessionId={sessionId}
  autoAdvance={{ enabled: true }}
>
  <Form />
</SecureFields>

const secureFields = new SecureFields({
  gr4vyId: 'example',
  environment: 'sandbox',
  sessionId: '...',
})

secureFields.setAutoAdvance({ enabled: true })

Custom field order

By default, auto advance follows the order: card number, expiry date, security code. You can override this with the fieldOrder option.

<SecureFields
  gr4vyId="example"
  environment="sandbox"
  sessionId={sessionId}
  autoAdvance={{
    enabled: true,
    fieldOrder: ['number', 'securityCode', 'expiryDate'],
  }}
>
  <Form />
</SecureFields>

secureFields.setAutoAdvance({
  enabled: true,
  fieldOrder: ['number', 'securityCode', 'expiryDate'],
})

The available field types for fieldOrder are number, expiryDate, and securityCode.

Reset

Each field instance exposes a clear() method to reset its value programmatically.

import { useRef } from 'react'
import { CardNumber } from '@gr4vy/secure-fields-react'

const Form = () => {
  const cardNumberRef = useRef(null)

  return (
    <>
      <CardNumber ref={cardNumberRef} />
      <button type="button" onClick={() => cardNumberRef.current?.clear()}>
        Clear
      </button>
    </>
  )
}

const cardNumberField = secureFields.addCardNumberField('#cc-number')

const clearButton = document.querySelector('#clear-button')
clearButton?.addEventListener('click', () => cardNumberField.clear())

Scheme icons

Display card scheme icons inside the card number field. Icons update in real-time as the user types and are refined when the API confirms the scheme. Pass true to show the detected scheme icon along with any additional schemes (for example co-branded cards):

<CardNumber showSchemeIcons />

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  showSchemeIcons: true,
})

For granular control, pass an object to choose which icons to display:

<CardNumber
  showSchemeIcons={{
    scheme: true,
    additionalSchemes: true,
    placeholders: true,
  }}
/>

const cardNumberField = secureFields.addCardNumberField('#cc-number', {
  showSchemeIcons: {
    scheme: true,
    additionalSchemes: true,
    placeholders: true,
  },
})

Scheme icon options

Option	Type	Default	Description
`scheme`	`boolean`	`false`	Show the detected card scheme icon.
`additionalSchemes`	`boolean`	`false`	Show additional scheme icons for co-branded cards.
`placeholders`	`boolean`	`false`	Show placeholder icons (Visa, Mastercard, Amex) before a scheme is detected.

A maximum of 3 icons are visible at any time. In co-branded scenarios, the primary scheme icon is displayed first, followed by additional schemes. Each icon is 48 px wide with 4 px spacing, so reserve at least 156 px of horizontal space inside the card number input to fit all 3 icons.

Get started

Integration guides

Best Practices

Resources

Features

Other

Secure Fields UX options

Auto focus

Input masking

Mask on blur

Real-time masking

Show last four digits

Mask input options

Programmatic masking

Auto advance

Custom field order

Reset

Scheme icons

Scheme icon options

​Auto focus

​Input masking

​Mask on blur

​Real-time masking

​Show last four digits

​Mask input options

​Programmatic masking

​Auto advance

​Custom field order

​Reset

​Scheme icons

​Scheme icon options

Auto focus

Input masking

Mask on blur

Real-time masking

Show last four digits

Mask input options

Programmatic masking

Auto advance

Custom field order

Reset

Scheme icons

Scheme icon options