> ## 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.

# Secure Fields UX options

> Learn how to configure opt-in user experience (UX) enhancements in Secure Fields, including auto focus, auto advance, input masking, scheme icons, and field reset.

## 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.

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber autoFocus />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    autoFocus: true,
  })
  ```
</CodeGroup>

<Info>
  Only one field should have `autoFocus` enabled at a time.
</Info>

## 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.

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber maskInput />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    maskInput: true,
  })
  ```
</CodeGroup>

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

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber
    maskInput={{
      character: '*',
    }}
  />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    maskInput: {
      character: '*',
    },
  })
  ```
</CodeGroup>

### Real-time masking

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

<Note>
  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.
</Note>

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber
    maskInput={{
      character: '•',
      maskOnInput: true,
    }}
  />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    maskInput: {
      character: '•',
      maskOnInput: true,
    },
  })
  ```
</CodeGroup>

### 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`.

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber
    maskInput={{
      character: '•',
      showLastFour: true,
    }}
  />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    maskInput: {
      character: '•',
      showLastFour: true,
    },
  })
  ```
</CodeGroup>

<Note>
  The `showLastFour` option is only available on card number fields.
</Note>

### 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.

<CodeGroup>
  ```jsx React theme={"system"}
  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>
      </>
    )
  }
  ```

  ```js Node / CDN theme={"system"}
  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()
    }
  })
  ```
</CodeGroup>

## Auto advance

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

<Warning>
  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.
</Warning>

<CodeGroup>
  ```jsx React theme={"system"}
  <SecureFields
    gr4vyId="example"
    environment="sandbox"
    sessionId={sessionId}
    autoAdvance={{ enabled: true }}
  >
    <Form />
  </SecureFields>
  ```

  ```js Node / CDN theme={"system"}
  const secureFields = new SecureFields({
    gr4vyId: 'example',
    environment: 'sandbox',
    sessionId: '...',
  })

  secureFields.setAutoAdvance({ enabled: true })
  ```
</CodeGroup>

### Custom field order

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

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

  ```js Node / CDN theme={"system"}
  secureFields.setAutoAdvance({
    enabled: true,
    fieldOrder: ['number', 'securityCode', 'expiryDate'],
  })
  ```
</CodeGroup>

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

## Reset

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

<CodeGroup>
  ```jsx React theme={"system"}
  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>
      </>
    )
  }
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number')

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

## 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):

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber showSchemeIcons />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    showSchemeIcons: true,
  })
  ```
</CodeGroup>

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

<CodeGroup>
  ```jsx React theme={"system"}
  <CardNumber
    showSchemeIcons={{
      scheme: true,
      additionalSchemes: true,
      placeholders: true,
    }}
  />
  ```

  ```js Node / CDN theme={"system"}
  const cardNumberField = secureFields.addCardNumberField('#cc-number', {
    showSchemeIcons: {
      scheme: true,
      additionalSchemes: true,
      placeholders: true,
    },
  })
  ```
</CodeGroup>

### 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. |

<Info>
  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.
</Info>