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

# Customizing UX Toolkit

Once you have a working integration, this page is your reference for customizing UX Toolkit's appearance and behavior — bootstrap configuration, themes, card art, and translations.

## Bootstrap properties

The `window.marqeta.bootstrap()` function is the single entry point for configuring UX Toolkit at runtime. The fields below are passed to it.

| **Field**                       | **Description**                                                                                                                                                 |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authParams.apiEndpoint`        | **Required.** Fully-qualified URL of your [<u>Customer Authentication API</u>](/docs/developer-guides/uxt-customer-authentication-api) endpoint.                     |
| `authParams.apiHeadersResolver` | Optional. A `HeadersInit` object — or a sync/async method returning one — used to pass session or auth token headers to your authentication API.                |
| `envName`                       | Optional. Environment being targeted. Allowable values: `sandbox` or `production`. Default: `production`.                                                       |
| `themeName`                     | Optional. The name of an existing theme created via the `/theme` endpoint. Default: `default`. See [<u>Themes</u>](#themes).                                    |
| `languageCode`                  | Optional. The language code for custom translation files uploaded via the `/translations` endpoint. Default: `en-US`. See [<u>Translations</u>](#translations). |

## **Bootstrap examples**

**Minimal — sandbox, default theme, default language:**

```text theme={null}
window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
});
```

**Full — custom theme, custom language, with auth headers:**

```text theme={null}
window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
    apiHeadersResolver: {
      "Authentication": "Bearer your-website-session-token-here"
    },
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
});
```

**Async headers resolver** (e.g., when your auth header changes per request):

```text theme={null}
window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
    apiHeadersResolver: async () => {
      const token = await getCurrentSessionToken();
      return { "Authentication": `Bearer ${token}` };
    },
  },
  envName: "production",
});
```

<h2 id="themes">
  **Themes**
</h2>

UX Toolkit components ship with a default theme; you can customize this theme so the components align more closely with your brand. Theming is a two-part workflow:

1. **Design your theme in [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/)** — an interactive design environment.
2. **Upload your theme via the API** — the `POST /theme` endpoint deploys it to the Marqeta platform for use with your card program.

### **Designing your theme in Studio**

[<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/) is an interactive theming environment where you can fine-tune the appearance of UX Toolkit UI components before integrating them. With Studio, you can preview and test the look-and-feel of components on various device types (mobile phone, tablet, and desktop).

While in Studio, you can click into each component to access its full functionality. Each component has both an **Overview** page and a **Customize** page that are linked together — any changes made on the Customize page carry over to the Overview page.

You can choose to work in Studio with or without authenticating:

* **Authenticated mode** — Studio is populated with your program's details and data instead of using the default Studio-simulated data.
* **Unauthenticated mode** — you work with the simulated data Studio provides.

<Warning>
  **Important**<br /> To work in Studio while authenticated, contact your Marqeta representative to obtain the Auth Params CLI script for your Auth Params. To run the Auth Params CLI script, you will need Node.js v16 (or later) installed and the items below.
</Warning>

| **Name**              | **Description**                                                                                                                          | **How to obtain**                                                                                                                                                                 |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client ID             | Your OAuth client identifier.                                                                                                            | Contact your Marqeta representative.                                                                                                                                              |
| Private PEM file name | Your private PEM file. This file should live in the same directory as the Auth Params CLI script. Do not share this PEM file externally. | The file name is created when generating your RSA key pair. See [Create RSA keys](/docs/developer-guides/uxt-getting-started#generate_your_rsa_key_pair) on the Getting Started page.. |
| User token            | Unique identifier of the user account holder. Allowable values: 36 char max.                                                             | Send a `POST /users` request to generate a user token.                                                                                                                            |
| OAuth URL             | The OAuth URL used for the client assertion.                                                                                             | Sandbox: `https://ux-toolkit-api-sandbox.marqeta.com` · Production: `https://ux-toolkit-api.marqeta.com`                                                                          |

Run the Auth Params CLI script, replacing each placeholder with your value from the table above:

```text theme={null}
node path/to/generateAuthParams.js \
  <client-id> \
  <private-pem-file-name> \
  <user-token> \
  <oauth-url>
```

For example, to generate auth params for the sandbox environment:

```text theme={null}
node path/to/generateAuthParams.js \
  example-client-id \
  private_key.pem \
  09d921f5-d6be-4d2d-aaa2-d2a796f93232 \
  https://ux-toolkit-api-sandbox.marqeta.com
```

When the script runs successfully, it prints an auth params JSON object to the terminal. Copy the full JSON object — you will paste it into Studio when authenticating.

**Example output:**

```text theme={null}
{
  "keyPair": {
    "publicJwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "<base64url>",
      "y": "<base64url>",
      "alg": "ES256"
    },
    "privateJwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "<base64url>",
      "y": "<base64url>",
      "alg": "ES256",
      "d": "<base64url>"
    }
  },
  "token": "<access_token>",
  "expiresAt": 1234567890000
}
```

#### **Authenticate when working with Studio**

To authenticate when working with Studio, follow these steps:

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-web-components/uxt-authentication-in-studio.png?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=e461c7c71d1f8c00b666c98a0a63ad35" alt="Uxt Authentication In Studio (1)" width="586" height="180" data-path="images/docs/developer-guides/uxt-web-components/uxt-authentication-in-studio.png" />
</Frame>

1. Access [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/).
2. In the upper-left corner of the screen, click the **Authentication** icon to load the modal window.
3. Select the **Authenticate** option button.
4. Paste the JSON output from the script into the **Auth Params** field, then click **Authenticate**. When the icon turns green, you have successfully switched to authenticated mode.

#### **Editing and sharing an existing Studio theme**

If you are part of a collaborative effort building a theme and want to share your work with others, share the theme as a JSON file. Consider hosting a copy of your theme's JSON file in your source control repository for safekeeping so you can monitor incremental changes made to it by team members.

Your Studio theme is not applied to your card product or program until you upload it to the Marqeta platform via the `POST /theme` endpoint (see [<u>Uploading your theme via the API</u>](#uploading-your-theme-via-the-api), below).

You cannot download and edit a Studio theme once it has been uploaded to the Marqeta platform. The Marqeta platform does not retain a version history of your theme's JSON file. To edit a locally saved copy of your theme:

1. Paste your theme's JSON content into [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/).
2. Make your modifications directly in the Studio interface.
3. Save the JSON file locally or in your source control repository.
4. Upload the JSON file to the Marqeta platform to overwrite the existing theme.

UX Toolkit does not limit you to a single theme per card program. You can define multiple themes and apply a different theme to each card product, for example. The only constraint is that all themes for a given card program must have unique names.

<Note>
  **Note**<br />If you close or refresh the browser tab where Studio is running, your customized theme values will be lost. Likewise, if you authenticate with Studio, you will be logged out after closing or refreshing the Studio tab.
</Note>

### **Uploading your theme via the API**

After you have developed your theme in Studio, save it as a JSON file and upload a copy to the Marqeta platform.

The example cURL below uploads a theme named `new-theme-name`:

```text theme={null}
curl --location 'https://ux-toolkit-api.marqeta.com/api/v1/theme' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {{BASE64_APPLICATION_AND_ADMIN_ACCESS_TOKENS}}' \
  --data '{
    "theme_name": "new-theme-name",
    "theme": {{THEME_JSON_HERE}}
  }'
```

Then update the call you make to `bootstrap()` to include the theme:

```text theme={null}
window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
  themeName: "new-theme-name",
});
```

For full reference of the `POST /theme` endpoint, see *Uploading a Studio theme* in the UX Toolkit API reference.

## **Card art**

UX Toolkit lets you upload custom card art for each card product in your program. You can submit up to three images per card product:

* An image displayed on the **front** of the card.
* An image displayed on the **back** of the card (digital cards only — virtual cards have no back image).
* A **thumbnail-sized image** of the front of the card.

If you do not upload card art, default images are displayed by UX Toolkit. Card art is shown in [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/) and in your application as part of the `mq-card` and `mq-card-list` components.

<Warning>
  **Important**<br />The card art you select must be preapproved by Marqeta, your bank, and the card network. It should adhere to card-network guidelines and may include details that are part of the bank approval process, such as the issuing bank name. Contact your Marqeta representative for details.
</Warning>

### **Digital (physical) cards**

**Front of card.** A digital version of the front of the physical card

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-digital-card-front.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=d1f0e10d0b99c2bd44991cc42ac4deb0" alt="Uxt Digital Card Front" width="300" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-digital-card-front.svg" />
</Frame>

**Back of card.** A digital version of the back of the physical card.

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-digital-card-back.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=b31dbc3f9f752bd2d3781ecc568d086b" alt="Uxt Digital Card Back" width="300" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-digital-card-back.svg" />
</Frame>

**Thumbnail.** An optional scaled-down version of the front-of-card image. If you don't submit a thumbnail, default imagery from the card network will be displayed instead.

### **Virtual cards**

**Front of card.** Represents the virtual card. Virtual cards have no back-of-card image.

<Frame>
  <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-getting-started/uxt-virtual-card.svg?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=93f13e117581bd9b64ed4840f42695c0" alt="Uxt Virtual Card" width="301" height="186" data-path="images/docs/developer-guides/uxt-getting-started/uxt-virtual-card.svg" />
</Frame>

**Thumbnail.** An optional scaled-down version of the virtual card image.

### **Card art specifications**

Submitted images must adhere to the following specifications:

| **Property**         | **Requirement**                                                                        |
| :------------------- | :------------------------------------------------------------------------------------- |
| File format          | PNG (`*.png`)                                                                          |
| Image orientation    | Landscape only                                                                         |
| File size on disk    | Maximum 5 MB per image. Avoid using a large file that must be resized for display.     |
| Image size on screen | Front/back: 1536 × 969 px (proportional to ISO ID-1 card size). Thumbnail: 60 × 36 px. |
| Corner radius        | 0.1233" (3.13182 mm)                                                                   |
| Resolution           | 72 PPI                                                                                 |
| Color model          | RGB                                                                                    |
| Color depth          | 16+ bit, non-interlaced                                                                |

### **Uploading card art to the Marqeta platform**

After your images have been approved by Marqeta, your bank, and the card network, you can upload them to the Marqeta platform for use in [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/) and your application.

You can upload card art via the `/cardproducts/cardart` endpoint of the UX Toolkit service. The example cURL below uploads `file.png`:

```text theme={null}
curl -X POST "https://ux-toolkit-api.marqeta.com/api/v1/cardproducts/cardart" \
  -H "Authorization: Basic $(echo -n '{{APPLICATION_TOKEN}}:{{ACCESS_TOKEN}}' | base64)" \
  -F "program_short_code={{program_short_code}}" \
  -F "card_product_token={{card_product_token}}" \
  -F "asset_type={{asset_type}}" \
  -F "file=@/path/to/your/file.png"
```

Valid `asset_type` values: `front`, `back`, `thumbnail`.

For full reference, see *Upload card art* in the UX Toolkit API reference.

<h2 id="translations">
  **Translations**
</h2>

UX Toolkit web components default to American English (`en-US`). The internationalization feature lets you change the language of components by uploading custom translation files via the `/translations` endpoint and referencing them in `bootstrap()`.

<Warning>
  **Important**<br />Before uploading translation files, ensure that they are linguistically accurate and representative of the user experience.
</Warning>

### **Working with custom translation files**

<Note>
  **Note**<br />Upload your custom translation files via the `/translations` endpoint *before* calling the `bootstrap()` function — `bootstrap()` references them by language code, so they must already exist on the Marqeta platform when the call is made.
</Note>

To include custom translation files when bootstrapping UX Toolkit:

1. Ensure your custom translation files are linguistically accurate.
2. Upload them via the `/translations` endpoint. (See *Upload custom translation files* in the UX Toolkit API reference.)
   <Warning>
     **Important**<br />The `/translations` endpoint requires the request body to include `program_short_code`, `language_code`, and `translations`. Missing any of these returns a `400 Bad Request` error.
   </Warning>
3. [<u>Test your files</u>](#testing-translations-in-studio) in [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/).
4. Update your `bootstrap()` call to include the language code:

```text theme={null}
window.marqeta.bootstrap({
  authParams: {
    apiEndpoint: "https://your-domain.com/oauth/token",
  },
  envName: "sandbox",
  themeName: "new-theme-name",
  languageCode: "es-ES"
});
```

For the full list of keys you can use in your custom translation files, contact your Marqeta onboarding specialist.

### **Testing translations in Studio**

You can use [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/) to test translation values.

<Note>
  **Note**<br />To test custom translation files, you must be authenticated within Studio.
</Note>

1. Request the translations object file for your target language from Marqeta.
2. Customize the values in the object file in your target language.
3. Send a request using the customized object to the `/translations` endpoint.
4. Authenticate in [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/). To switch to authenticated mode, follow these steps:
   <Frame>
     <img src="https://mintcdn.com/marqeta-b295cded/hYmh6YsXz54defql/images/docs/developer-guides/uxt-web-components/uxt-authentication-in-studio.png?fit=max&auto=format&n=hYmh6YsXz54defql&q=85&s=e461c7c71d1f8c00b666c98a0a63ad35" alt="Uxt Authentication In Studio" width="586" height="180" data-path="images/docs/developer-guides/uxt-web-components/uxt-authentication-in-studio.png" />
   </Frame>
   1. Access [<u>Studio</u>](https://studio.ux-toolkit.marqeta.com/).
   2. In the upper-left corner of the screen, click the **Authentication** icon to load the modal window.
   3. Select the **Authenticate** option button.
   4. Paste the JSON output from the script into the **Auth Params** field, then click **Authenticate**. When the icon turns green, you have successfully switched to authenticated mode.
5. In Studio, click the **globe** icon in the top menu navigation bar to confirm your custom translations have been applied. Available languages are listed in the drop-down beneath the globe icon.
6. Select a language from the list.

<Note>
  **Note**<br />Use the **Customize** tab in Studio to view any updates that you have made to the components' display language.
</Note>