Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 />
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 />
To use a different masking character, pass an object with character: 
<CardNumber
  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,
  }}
/>

​
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,
  }}
/>
The showLastFour option is only available on card number fields.

​
Mask input options

OptionTypeDefaultDescription
characterstring•The character used to replace digits.
showLastFourbooleanfalseKeep the last four digits visible when the card number is valid. Only available on card number fields.
maskOnInputbooleanfalseMask 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>
    </>
  )
}

​
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>

​
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>
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>
    </>
  )
}

​
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 />
For granular control, pass an object to choose which icons to display: 
<CardNumber
  showSchemeIcons={{
    scheme: true,
    additionalSchemes: true,
    placeholders: true,
  }}
/>

​
Scheme icon options

OptionTypeDefaultDescription
schemebooleanfalseShow the detected card scheme icon.
additionalSchemesbooleanfalseShow additional scheme icons for co-branded cards.
placeholdersbooleanfalseShow 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.