> ## 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); }"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.