> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customise Component

> Customise Cashfree.js components by configuring appearance, styling, and behaviour options to match your design system on a custom-built checkout page.

Each `Cashfree.js` component is initialised with a configuration object that allows you to customise both its behaviour and appearance and integrate it with your application's design system.

<Note>
  All configuration options are optional, components use default styles if not specified. The style object supports most CSS properties in camelCase format. Custom fonts in the `fonts` array are loaded automatically before the component renders. Use `disabled` to temporarily prevent user interaction (e.g., during form submission). Use `loader` to show or hide loading states while the component initialises.
</Note>

Configuration is passed as the second argument to `cashfree.create()`:

```javascript theme={"dark"}
const options = {
  classes:  { /* CSS class names by state */ },
  style:    { /* inline styles by state */   },
  fonts:    [ /* custom font definitions */  ],
  values:   { /* pre-filled values */        },
  disabled: false,
  loader:   true,
};

const component = cashfree.create("componentType", options);
component.mount("#container-id");
```

## Configuration options

Select an option below to jump to its detailed customisation guide.

<CardGroup cols={3}>
  <Card title="classes" icon="code" href="#classes">
    CSS class names applied per state
  </Card>

  <Card title="style" icon="paintbrush" href="#style">
    Inline CSS styles applied per state
  </Card>

  <Card title="fonts" icon="font" href="#fonts">
    Custom fonts to load inside the component
  </Card>

  <Card title="values" icon="keyboard" href="#values">
    Initial values to pre-fill the component
  </Card>

  <Card title="disabled" icon="circle-exclamation" href="#disabled">
    Load the component in a disabled state
  </Card>

  <Card title="loader" icon="spinner" href="#loader">
    Show a skeleton loader during initialisation
  </Card>
</CardGroup>

## Appearance and styling

Use these options to define how the component looks and how it integrates with your application's design system.

### classes

Type: `object`

Apply CSS class names to the component container. The SDK automatically adds or removes classes based on the component's state. You do not need to add them to your HTML manually.

<Note>
  Define these classes in your application's CSS. The SDK applies them dynamically; do not add them to the DOM container yourself.
</Note>

#### States

Each state maps to a CSS class you define in your stylesheet. The SDK adds and removes these classes automatically as the component's state changes.

| State      | When it is applied                                   |
| ---------- | ---------------------------------------------------- |
| `base`     | Always applied. Use this for base or default styling |
| `complete` | Applied when the user has entered a valid value      |
| `empty`    | Applied when no value has been entered               |
| `focus`    | Applied when the component has keyboard focus        |
| `invalid`  | Applied when the component contains invalid data     |
| `disabled` | Applied when the component is disabled               |

#### Default values

If you do not supply your own class names, the SDK uses the following internal defaults. These classes are not exposed in your stylesheet, so override them by specifying custom names.

```json theme={"dark"}
{
  "base":     "cf-base-private",
  "complete": "cf-complete-private",
  "empty":    "cf-empty-private",
  "focus":    "cf-focus-private",
  "invalid":  "cf-invalid-private",
  "disabled": "cf-disabled-private"
}
```

#### Usage

Pass a `classes` object inside `options` when calling `cashfree.create()`. Only include the states you want to override; any omitted states fall back to their defaults.

```javascript theme={"dark"}
const options = {
  classes: {
    base:     "my-input",
    focus:    "input-focused",
    invalid:  "input-error",
    complete: "input-complete",
  },
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

#### CSS examples by state

Expand any state below to see a JavaScript snippet alongside a matching CSS example.

<AccordionGroup>
  <Accordion title="base: default styling">
    Applied to the container at all times. Use this for base or default styling. If you do not provide a value, the default `cf-base-private` is applied.

    ```javascript theme={"dark"}
    const options = {
      classes: { base: "my-base" },
    };
    ```

    ```css theme={"dark"}
    .my-base {
      padding: 5px;
      border: 1px solid #ccc;
      border-radius: 4px;
    }
    ```
  </Accordion>

  <Accordion title="complete: valid input">
    Applied when the user has entered a complete, valid value (for example, a valid card number). Note that not all components apply a complete class. Default is `cf-complete-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { complete: "my-complete" },
    };
    ```

    ```css theme={"dark"}
    .my-complete {
      border-color: #28a745;
      background-color: #f0f9f7;
    }
    ```
  </Accordion>

  <Accordion title="empty: no value entered">
    Applied when the component has no value, for example when the user has not yet typed anything. Default is `cf-empty-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { empty: "my-empty" },
    };
    ```

    ```css theme={"dark"}
    .my-empty {
      box-shadow: 1px 1px 4px rgba(0, 0, 0, 0.1);
    }
    ```
  </Accordion>

  <Accordion title="focus: component is focused">
    Applied when the component receives keyboard focus, for example when the user clicks into the card number input. Default is `cf-focus-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { focus: "my-focus" },
    };
    ```

    ```css theme={"dark"}
    .my-focus {
      border-color: #0066cc;
      box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.1);
    }
    ```
  </Accordion>

  <Accordion title="invalid: invalid input">
    Applied when the component contains invalid data, for example when the user has entered an incorrect card number. Default is `cf-invalid-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { invalid: "my-invalid" },
    };
    ```

    ```css theme={"dark"}
    .my-invalid {
      border-color: #C1292E;
      color: #C1292E;
    }
    ```
  </Accordion>

  <Accordion title="disabled: component is disabled">
    Applied when you have disabled the component. The `classes.disabled` styling is combined with any `style.base[":disabled"]` rules you have set. Default is `cf-disabled-private`.

    ```javascript theme={"dark"}
    const options = {
      classes: { disabled: "my-disabled" },
    };
    ```

    ```css theme={"dark"}
    .my-disabled {
      opacity: 0.6;
      cursor: not-allowed;
    }
    ```
  </Accordion>
</AccordionGroup>

### style

Type: `object`

Apply inline CSS styles directly to the component's content. The style object supports most CSS properties in **camelCase** format (for example, `fontSize` instead of `font-size`). Styles can be defined per state: `base`, `complete`, `empty`, and `invalid`.

#### Default values

The SDK applies the following style defaults when no `style` option is provided. Only `base.fontSize` and `invalid.color` are set out of the box; all other states start empty.

```json theme={"dark"}
{
  "base":     { "fontSize": "16px" },
  "complete": {},
  "empty":    {},
  "invalid":  { "color": "#C1292E" }
}
```

#### Usage

Pass a `style` object inside `options` to override the default appearance for one or more states. You only need to include the states and properties you want to change.

```javascript theme={"dark"}
const options = {
  style: {
    base: {
      color:      "#333",
      fontSize:   "16px",
      fontFamily: "Roboto, sans-serif",
      padding:    "12px",
    },
    complete: {
      color: "#28a745",
    },
    invalid: {
      color: "#C1292E",
    },
  },
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

#### Pseudo-classes and pseudo-elements

You can target interactive states and placeholder text by nesting pseudo-class and pseudo-element keys inside any state object. Use these inside `style.base` (or any other state) as shown below. Supported values:

| Pseudo-class / element | Description                  |
| ---------------------- | ---------------------------- |
| `:hover`               | Cursor is over the component |
| `:focus`               | Component has keyboard focus |
| `:disabled`            | Component is disabled        |
| `::placeholder`        | Placeholder text             |

```javascript theme={"dark"}
const options = {
  style: {
    base: {
      fontSize:        "16px",
      color:           "#333",
      backgroundColor: "#fff",
      "::placeholder": {
        color: "#999",
      },
      ":hover": {
        backgroundColor: "#f9f9f9",
      },
      ":focus": {
        outline:     "none",
        borderColor: "#0066cc",
      },
      ":disabled": {
        backgroundColor: "#f0f0f0",
        color:           "#999",
      },
    },
  },
};
```

### fonts

Type: `array`

Load custom fonts to match your application's typography. Fonts specified in the `fonts` array are loaded automatically before the component renders, and are injected into the component's iframe so they render correctly in the secure context.

#### Default value

When no fonts are specified, the component inherits whatever fonts are already available in the browser environment.

```javascript theme={"dark"}
[]
```

#### Option 1: CSS URL

Reference a CSS file that contains [@font-face](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) definitions (for example, a Google Fonts URL):

```javascript theme={"dark"}
const options = {
  fonts: [
    {
      cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
    },
  ],
};
```

#### Option 2: Font file with parameters

Specify individual font files with full parameters. Both `src` and `fontFamily` are required; all other properties are optional.

```javascript theme={"dark"}
const options = {
  fonts: [
    {
      fontFamily:   "Nova Mono",
      fontStyle:    "normal",
      fontWeight:   400,
      fontDisplay:  "swap",
      src:          "url(https://fonts.gstatic.com/s/novamono/v18/Cn-0JtiGWQ5Ajb--MRKvZ2ZZj9AtSw.woff2)",
      unicodeRange: "U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD",
    },
  ],
};
```

You can specify multiple fonts and reference them by `fontFamily` name inside the `style` option.

## Behaviour and initialisation

Control the initial state, disabled status, and loading experience of your components.

### values

Type: `object`

Pre-fill a component with a starting value. The available keys depend on the component type. Visit sections under different [components](/payments/online/element/upi) to get all the available keys.

#### Default value

If no initial values are provided, the component renders empty and waits for user input.

```javascript theme={"dark"}
{}
```

#### Usage

Pass the keys relevant to the component type you are creating. Keys that are not recognised by the component are silently ignored.

```javascript theme={"dark"}
const options = {
  values: {
    cardHolder: "Jane Doe",
  },
};

const component = cashfree.create("cardHolder", options);
component.mount("#cardholder-container");
```

#### Examples by component

Expand the component type below to see the accepted value keys and an example pre-filled value.

<AccordionGroup>
  <Accordion title="Card Holder">
    ```javascript theme={"dark"}
    const options = {
      values: {
        cardHolder: "Jane Doe",
      },
    };
    ```
  </Accordion>

  <Accordion title="UPI Collect">
    ```javascript theme={"dark"}
    const options = {
      values: {
        upiId: "testsuccess@gocash",
      },
    };
    ```
  </Accordion>
</AccordionGroup>

### disabled

Type: `boolean`

Load the component in a disabled state. Use this to temporarily prevent user interaction (e.g., during form submission). When `true`, the component applies `classes.disabled` and `style.base[":disabled"]` styling automatically.

#### Default value

Components load in an enabled (interactive) state by default.

```javascript theme={"dark"}
false
```

#### Usage

Set `disabled` to `true` when you need to prevent user interaction, for example during form submission or while an earlier step in your checkout flow is still loading.

```javascript theme={"dark"}
const options = {
  disabled: true,
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

### loader

Type: `boolean`

Show or hide a skeleton loader UI while the component initialises. Use this to control loading states during initialisation. Not all components support this option.

#### Default value

The skeleton loader is enabled by default, so users see a visual placeholder immediately while the component iframe initialises.

```javascript theme={"dark"}
true
```

#### Usage

Set `loader` to `false` if you prefer to handle the loading state yourself, or if the component does not support it.

```javascript theme={"dark"}
const options = {
  loader: true,
};

const component = cashfree.create("cardNumber", options);
component.mount("#card-number-container");
```

## Complete example

The following example demonstrates all configuration options used together to create a fully customised payment component:

```javascript theme={"dark"}
const cardNumberOptions = {
  classes: {
    base: "my-input",
    focus: "input-focused",
    invalid: "input-error",
    complete: "input-complete",
  },
  fonts: [
    {
      family: "Roboto",
      src: "https://fonts.googleapis.com/css2?family=Roboto",
    },
  ],
  style: {
    base: {
      color: "#333",
      fontSize: "16px",
      fontFamily: "Roboto, sans-serif",
      padding: "12px",
      backgroundColor: "#fff",
      border: "1px solid #ccc",
      borderRadius: "4px",
    },
    focus: {
      borderColor: "#0066cc",
    },
    invalid: {
      borderColor: "#ff3333",
      color: "#ff3333",
    },
  },
  disabled: false,
  loader: true,
};

const cardNumber = cashfree.create("cardNumber", cardNumberOptions);
cardNumber.mount("#card-number-container");
```

<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0 0-2-2H3z" />

      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/payments/online/element/introduction">Element SDK Introduction</a></li>
    <li><a href="/docs/payments/online/element/component-overview">Component Overview</a></li>
    <li><a href="/docs/payments/online/element/cards">Card Components</a></li>
    <li><a href="/docs/payments/online/element/upi">UPI Components</a></li>
    <li><a href="/docs/payments/online/element/payment-options">Payment Options</a></li>
  </ul>
</div>