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

# Appearance Reference

> Complete list of all checkout appearance customization options

Complete list of `appearance` fields for Ozura Checkout. The hosted page uses a **centered card** layout on desktop (form left, summary right inside the card; brand bar above). Field names match the Checkout API.

<Info>
  **Naming note:** `leftSideBackground` styles the **order summary** panel (the visually **right** column inside the card). `rightSideBackground` styles the **payment form** panel (the visually **left** column). The names are historical; use the descriptions below, not the word “left/right” alone.
</Info>

## Global Colors

| Key                 | Type | Description                                                                                                                                                                                  |
| :------------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryColor`      | Hex  | Main brand color (accents, active payment-method border, default pay button chain)                                                                                                           |
| `primaryHoverColor` | Hex  | Hover for primary-colored controls                                                                                                                                                           |
| `secondaryColor`    | Hex  | Secondary accent where used                                                                                                                                                                  |
| `backgroundColor`   | Hex  | Sets global/custom fallbacks (inputs, many panels). **Not** the outer lavender canvas—use `cssVariables.page-background` (see [Customize Appearance](/guides/payments/checkout/appearance)). |
| `textColor`         | Hex  | Default text                                                                                                                                                                                 |
| `borderColor`       | Hex  | Borders and some dividers                                                                                                                                                                    |

## Layout (Desktop — inside the card)

| Key                   | Type    | Description                                                                           |
| :-------------------- | :------ | :------------------------------------------------------------------------------------ |
| `leftSideBackground`  | Hex     | **Order summary** panel background (right portion of the card)                        |
| `rightSideBackground` | Hex     | **Payment form** panel background (left portion of the card)                          |
| `formBackground`      | Hex     | Form container background                                                             |
| `dividerColor`        | Hex     | Divider color; on mobile, used with `showTopDivider` for a line under the top section |
| `showTopDivider`      | Boolean | When `true` and `dividerColor` is set, draws a divider under the mobile header area   |

## Layout (Mobile)

| Key                         | Type    | Description                                                                                                                              |
| :-------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `mobileBackground`          | Hex     | Mobile sections (summary, donation block, etc.)                                                                                          |
| `mobileTopBackground`       | Hex     | Top branding / header band                                                                                                               |
| `mobileBottomBackground`    | Hex     | Lower sections where applied                                                                                                             |
| `mobileFormBackgroundColor` | Hex     | Form area background                                                                                                                     |
| `mobileStickyTop`           | Boolean | If `true`, pins the mobile branding header and order summary to the top of the viewport as the customer scrolls down to fill in the form |

## Typography

| Key          | Type   | Description                                                                       |
| :----------- | :----- | :-------------------------------------------------------------------------------- |
| `fontFamily` | String | Font stack (sanitized); does **not** style the fixed “Powered by OzuraPay” footer |
| `fontSize`   | String | `sm`, `base`, `lg`, `xl` (drives scaled sizing on the page)                       |
| `fontWeight` | String | In API/types; **not applied** by checkout today                                   |

## Spacing & Borders

| Key            | Type   | Description                              |
| :------------- | :----- | :--------------------------------------- |
| `spacing`      | String | `compact`, `normal`, `spacious`          |
| `borderRadius` | String | `none`, `sm`, `base`, `lg`, `xl`, `full` |

## Text Colors

| Key                  | Type | Description                                                 |
| :------------------- | :--- | :---------------------------------------------------------- |
| `headingTextColor`   | Hex  | Titles and headings (including merchant name styling chain) |
| `bodyTextColor`      | Hex  | Body text where wired                                       |
| `labelTextColor`     | Hex  | Form labels                                                 |
| `formLabelTextColor` | Hex  | Labels inside card/ACH sections                             |
| `secondaryTextColor` | Hex  | Secondary/helper text                                       |
| `amountTextColor`    | Hex  | Amount displays                                             |
| `emailTextColor`     | Hex  | Email field                                                 |
| `cardTextColor`      | Hex  | Card payment fields                                         |
| `achTextColor`       | Hex  | ACH / bank fields                                           |

## Input Fields

| Key                     | Type | Description                                                                                                       |
| :---------------------- | :--- | :---------------------------------------------------------------------------------------------------------------- |
| `inputBackgroundColor`  | Hex  | Input background                                                                                                  |
| `inputBorderColor`      | Hex  | Default border (the new layout often uses borderless inputs with a focus ring; variable still applies where used) |
| `inputFocusBorderColor` | Hex  | Focus border where used                                                                                           |
| `inputErrorBorderColor` | Hex  | Error state                                                                                                       |

## Primary Button (Pay / Donate)

| Key                     | Type | Description           |
| :---------------------- | :--- | :-------------------- |
| `buttonBackgroundColor` | Hex  | Pay button background |
| `buttonHoverColor`      | Hex  | Pay button hover      |
| `buttonBorderColor`     | Hex  | Pay button border     |

The **button label** (e.g. `Pay $10.00 + Tax`, `Donate $25.00`) is **not** a single `appearance` field—it is computed from donation mode, tax estimate, country, and tax-exempt flags.

## Payment Method Selector

| Key                                        | Type | Description                                                       |
| :----------------------------------------- | :--- | :---------------------------------------------------------------- |
| `paymentMethodBorderColor`                 | Hex  | Border around the payment method **container** and related inputs |
| `paymentMethodButtonBackgroundColor`       | Hex  | Inactive method tab background                                    |
| `paymentMethodButtonHoverBackgroundColor`  | Hex  | Hover background                                                  |
| `paymentMethodButtonActiveBackgroundColor` | Hex  | Selected method tab background                                    |
| `paymentMethodButtonTextColor`             | Hex  | Method tab text                                                   |
| `paymentMethodIconColor`                   | Hex  | Icons on method tabs                                              |

## Mobile Text & Input Overrides

| Key                           | Type | Description                |
| :---------------------------- | :--- | :------------------------- |
| `mobileHeadingTextColor`      | Hex  | Headings on mobile         |
| `mobileAmountTextColor`       | Hex  | Amount on mobile           |
| `mobileSecondaryTextColor`    | Hex  | Secondary text on mobile   |
| `mobileLabelTextColor`        | Hex  | Labels on mobile           |
| `mobileInputTextColor`        | Hex  | Input text on mobile       |
| `mobileInputBackgroundColor`  | Hex  | Input background on mobile |
| `mobileInputBorderColor`      | Hex  | Input border on mobile     |
| `mobileButtonBackgroundColor` | Hex  | Pay button on mobile       |
| `mobileButtonHoverColor`      | Hex  | Pay button hover on mobile |
| `mobileFormBackgroundColor`   | Hex  | Form section on mobile     |

## Cancel Button

| Key                           | Type   | Description                              |
| :---------------------------- | :----- | :--------------------------------------- |
| `cancelButtonText`            | String | Label (default: `Cancel and Return`)     |
| `cancelButtonBackgroundColor` | Hex    | Background                               |
| `cancelButtonTextColor`       | Hex    | Text color                               |
| `cancelButtonHoverColor`      | Hex    | **Text** color on hover (not background) |
| `cancelButtonBorderColor`     | Hex    | Border (`1px solid …` when set)          |

## Branding

| Key                | Type    | Description                                                                            |
| :----------------- | :------ | :------------------------------------------------------------------------------------- |
| `logoUrl`          | URL     | Logo image (HTTPS)                                                                     |
| `logoPosition`     | String  | `inline` or `top`                                                                      |
| `logoMaxHeight`    | String  | In API; **not read** by live logo component                                            |
| `showMerchantName` | Boolean | Show name with logo (see [Customize Appearance](/guides/payments/checkout/appearance)) |
| `hideBranding`     | Boolean | In API; **not used** by the checkout page today                                        |

The **store name** comes from the required **`merchantName`** field when you create the session (stored on the session for the UI).

## Cart Display (Itemized Checkout)

When using an `items` array:

| Key                          | Type   | Description                                      |
| :--------------------------- | :----- | :----------------------------------------------- |
| `cartFontFamily`             | String | Font for cart block (falls back to `fontFamily`) |
| `cartProductNameColor`       | Hex    | Product name                                     |
| `cartBrandColor`             | Hex    | Brand line                                       |
| `cartDescriptionColor`       | Hex    | Description                                      |
| `cartVariantColor`           | Hex    | Variant line                                     |
| `cartCategoryColor`          | Hex    | Category                                         |
| `cartSkuColor`               | Hex    | SKU                                              |
| `cartPriceColor`             | Hex    | Price                                            |
| `cartOriginalPriceColor`     | Hex    | Strikethrough price                              |
| `cartQuantityColor`          | Hex    | Quantity                                         |
| `cartDiscountBadgeColor`     | Hex    | Discount badge background                        |
| `cartDiscountBadgeTextColor` | Hex    | Discount badge text                              |
| `cartTaxFreeColor`           | Hex    | Tax-free indicator                               |
| `cartSubtotalColor`          | Hex    | Subtotal                                         |
| `cartTotalColor`             | Hex    | Total                                            |
| `cartTaxNoteColor`           | Hex    | Tax note text                                    |

Line content (images, badges, links) is controlled by each [cart item](/guides/payments/checkout/create-session) field, not `appearance`.

## API Warnings

Session and payment-link creation may return **`warnings`** (not errors) when colors fail WCAG contrast checks or mobile/desktop combinations look mismatched. Surface these in your dashboard when present.

## Pre-Made Themes

### Minimal Light

```json theme={null}
{
  "appearance": {
    "primaryColor": "#6366F1",
    "primaryHoverColor": "#4F46E5",
    "backgroundColor": "#FAFAFA",
    "textColor": "#1F2937",
    "fontFamily": "Poppins, sans-serif",
    "borderRadius": "lg"
  }
}
```

### Violet Dark Mode

```json theme={null}
{
  "appearance": {
    "primaryColor": "#8b5cf6",
    "buttonBackgroundColor": "#8b5cf6",
    "leftSideBackground": "#0f0a1a",
    "rightSideBackground": "#1a0f2e",
    "formBackground": "#1a0f2e",
    "headingTextColor": "#ffffff",
    "textColor": "#e5e7eb",
    "inputBackgroundColor": "#1a0f2e",
    "inputBorderColor": "#8b5cf6",
    "cssVariables": {
      "page-background": "#0c0518"
    }
  }
}
```

### Emerald Clean

```json theme={null}
{
  "appearance": {
    "primaryColor": "#10b981",
    "buttonBackgroundColor": "#10b981",
    "buttonHoverColor": "#059669",
    "inputFocusBorderColor": "#10b981",
    "borderRadius": "base"
  }
}
```

## Custom CSS

| Key            | Type   | Description                                                                                                                                                                                                                                     |
| :------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customCss`    | String | Raw CSS injected in a `<style>` block (max **10,000** characters; blocked patterns below)                                                                                                                                                       |
| `cssVariables` | Object | Keys become `--custom-{key}` on the document root. Values are sanitized as **colors or size/dimension values** (`px`, `em`, `%`, etc.) — values that parse as neither are silently dropped. Max **100** entries; values max **200** characters. |

### Security Restrictions

These patterns cause `customCss` to be **rejected** (and may fail API validation):

* `url(`
* `@import`
* `javascript:`
* `expression(`
* `behavior:`, `binding:`, `-moz-binding`, `-webkit-binding`
* CSS hex escape sequences (e.g. `\3c`)

### Available CSS Classes (non-exhaustive)

| Class                      | What It Styles                                                     |
| :------------------------- | :----------------------------------------------------------------- |
| `.checkout-container`      | Root container                                                     |
| `.checkout-form-container` | Payment form wrapper                                               |
| `.checkout-input`          | Text inputs (legacy class; many fields use shared checkout styles) |
| `.checkout-submit-button`  | Primary pay button                                                 |
| `.checkout-error`          | Error messages                                                     |

### Example: Gradient Button

```json theme={null}
{
  "appearance": {
    "primaryColor": "#10b981",
    "customCss": ".checkout-submit-button { background: linear-gradient(135deg, #10b981, #059669); }"
  }
}
```