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

# Theme reference

> Reference every Widget theme field, border-radius scale, and CSS custom property.

## Overview

Beyond colors, the Swap Widget and Deposit Widget offer extensive configuration options for layout, borders, header visibility, and custom styling. These options allow you to control each widget's structure and behavior to match your application's design system.

## Theme Type Definition

The complete theme configuration type:

```typescript theme={null}
export type ThemeData = {
  buttonTextColor?: string,
  logo?: string,
  tertiary?: string,
  primary?: ThemeColor,
  secondary?: ThemeColor,
  warning?: StatusColor,
  error?: StatusColor,
  success?: StatusColor,
  borderRadius?: 'none' | 'small' | 'medium' | 'large' | 'extraLarge' | 'default',
  enablePortal?: boolean,
  enableWideVersion?: boolean,
  header?: {
    hideMenu?: boolean,
    hideTabs?: boolean,
    hideWallets?: boolean,
  },
  cardBackgroundStyle?: React.CSSProperties,
  hidePoweredBy?: boolean
}
```

The color schema deep-merges the supplied fields over the `default` theme, so you can override only the values you need. The outer `LayerswapProvider` receives `config.theme` shallowly; keep related nested values together when composing theme objects in your own code.

Named Hosted Page presets do not work through `initialValues.theme` in the Widget packages. Use `config.theme` with this `ThemeData` shape.

## Border Radius

<ResponseField name="borderRadius" type="'none' | 'small' | 'medium' | 'large' | 'extraLarge' | 'default'">
  Controls the roundness of corners for cards, buttons, and other UI elements throughout the widget.
</ResponseField>

### Available Options

| Value          | `sm` | `md` | `lg` | `xl` | `2xl` | `3xl` |
| -------------- | ---: | ---: | ---: | ---: | ----: | ----: |
| `'none'`       |    0 |    0 |    0 |    0 |     0 |     0 |
| `'small'`      |    2 |    4 |    6 |    8 |    12 |    16 |
| `'medium'`     |    4 |    6 |    8 |   12 |    16 |    24 |
| `'large'`      |    6 |    8 |   12 |   16 |    24 |    24 |
| `'extraLarge'` |    8 |   12 |   16 |   24 |    24 |    24 |
| `'default'`    |    4 |    6 |    8 |   12 |    16 |    24 |

Values are pixels. `--ls-border-radius-full` is always `9999px`; `--ls-border-radius-default` uses the `sm` value of the selected scale.

**Example:**

```typescript theme={null}
const theme = {
  borderRadius: 'medium',
  // ... other theme properties
}
```

**Visual Impact:**

* Affects all cards, modals, and containers
* Applies to buttons and interactive elements
* Influences input fields and dropdowns
* Consistent across all widget components

## Header Customization

<ResponseField name="header" type="object">
  Configuration object for widget header visibility options. Control which elements appear in the widget header.
</ResponseField>

### Hide Menu

<ResponseField name="header.hideMenu" type="boolean">
  Hide the menu button in the widget header. Set to `true` to remove the menu icon.
</ResponseField>

```typescript theme={null}
header: {
  hideMenu: true
}
```

### Hide Tabs

<ResponseField name="header.hideTabs" type="boolean">
  Hide the tab switcher (swap / cex / deposit) in the widget header. Set to `true` to lock users into a specific flow.
</ResponseField>

```typescript theme={null}
header: {
  hideTabs: true
}
```

<Note>
  When `hideTabs` is `true`, users can only access the flow specified in `initialValues.defaultTab`. See [Initial values & flows](/widget/initial-values).
</Note>

### Hide Wallets

<ResponseField name="header.hideWallets" type="boolean">
  Hide the wallet connection display in the widget header. Set to `true` to remove the wallet indicator.
</ResponseField>

```typescript theme={null}
header: {
  hideWallets: true
}
```

### Complete Header Example

```typescript theme={null}
const theme = {
  header: {
    hideMenu: true,
    hideTabs: true,
    hideWallets: true,
  },
  // ... other theme properties
}
```

This configuration creates a minimal header with no menu, no tab switcher, and no wallet display.

## Card Background Style

<ResponseField name="cardBackgroundStyle" type="React.CSSProperties">
  Custom CSS styles for card backgrounds. Accepts any valid React CSS properties, enabling transparent backgrounds, blur effects, borders, and more.
</ResponseField>

### Basic Transparent Background

```typescript theme={null}
cardBackgroundStyle: {
  backgroundColor: "transparent"
}
```

### Glassmorphism Effect

```typescript theme={null}
cardBackgroundStyle: {
  backgroundColor: "rgba(255, 255, 255, 0.01)",
  backdropFilter: "blur(20px)",
  border: "1px solid rgba(255, 255, 255, 0.1)"
}
```

### Custom Gradient

```typescript theme={null}
cardBackgroundStyle: {
  background: "linear-gradient(135deg, rgba(99, 102, 241, 0.1) 0%, rgba(139, 92, 246, 0.1) 100%)",
  border: "1px solid rgba(99, 102, 241, 0.2)"
}
```

### With Shadow

```typescript theme={null}
cardBackgroundStyle: {
  backgroundColor: "#1a1a2e",
  boxShadow: "0 20px 60px rgba(0, 0, 0, 0.3)",
  border: "1px solid rgba(255, 255, 255, 0.05)"
}
```

**Supported Properties:**

* `backgroundColor` / `background`
* `backdropFilter`
* `border` / `borderRadius`
* `boxShadow`
* `padding` / `margin`
* Any valid CSS property that works with React's `style` prop

<Note>
  The `cardBackgroundStyle` applies to the main widget card container. It does not override the `borderRadius` theme property - use the `borderRadius` field for consistent corner styling.
</Note>

## Layout Options

<ResponseField name="enableWideVersion" type="boolean">
  Render the widget in its wide layout. Useful when the widget is the main content of a page rather than a compact embed.
</ResponseField>

<ResponseField name="enablePortal" type="boolean">
  Render widget dialogs and dropdowns in a document-level portal instead of inside the widget container. Enable this if your container clips overlays (e.g. `overflow: hidden` ancestors).
</ResponseField>

<ResponseField name="logo" type="string">
  Logo accent color as an RGB triple string (e.g. `'255, 50, 114'`).
</ResponseField>

## Hide Powered By

<ResponseField name="hidePoweredBy" type="boolean">
  Remove the "Powered by Layerswap" branding from the widget footer. Set to `true` to hide the attribution.
</ResponseField>

```typescript theme={null}
const theme = {
  hidePoweredBy: true,
  // ... other theme properties
}
```

## Complete Configuration Example

Here's a complete example combining all configuration options:

```tsx theme={null}
import { LayerswapWidget } from '@layerswap/widget-react';

// Module scope, so the config object stays referentially stable
const widgetConfig = {
  apiKey: 'YOUR_API_KEY',
  version: 'mainnet',
  theme: {
    // Colors (see Colors documentation)
    primary: {
      DEFAULT: "99, 102, 241",
      500: "99, 102, 241",
      text: "255, 255, 255"
    },
    secondary: {
      DEFAULT: "30, 41, 59",
      500: "30, 41, 59",
      text: "148, 163, 184"
    },
    tertiary: "148, 163, 184",
    buttonTextColor: "255, 255, 255",

    // Layout & Structure
    borderRadius: "large",

    // Header Configuration
    header: {
      hideMenu: true,
      hideTabs: false,
      hideWallets: false,
    },

    // Advanced Styling
    cardBackgroundStyle: {
      backgroundColor: "rgba(255, 255, 255, 0.05)",
      backdropFilter: "blur(10px)",
      border: "1px solid rgba(255, 255, 255, 0.1)"
    },

    // Branding
    hidePoweredBy: false
  },
  initialValues: {
    defaultTab: 'swap',
    to: 'ARBITRUM_MAINNET',
  }
};

export default function App() {
  return <LayerswapWidget config={widgetConfig} />;
}
```

## CSS Custom Properties

The theme is emitted as CSS custom properties on the widget container, which you can inspect (and, for advanced cases, override with your own CSS):

* `--ls-colors-primary`, `--ls-colors-primary-<100–900>`, `--ls-colors-primary-text`
* `--ls-colors-secondary`, `--ls-colors-secondary-<100–900>`, `--ls-colors-secondary-text`
* `--ls-colors-button`, `--ls-colors-logo`, `--ls-colors-text-tertiary`
* `--ls-colors-warning-foreground` / `--ls-colors-warning-background` (same for `error` and `success`)
* `--ls-border-radius-none`, `--ls-border-radius-sm`, `--ls-border-radius-md`, `--ls-border-radius-lg`, `--ls-border-radius-xl`, `--ls-border-radius-2xl`, `--ls-border-radius-3xl`, `--ls-border-radius-full`, `--ls-border-radius-default`

Prefer the `theme` object where possible — CSS-level overrides bypass the theme's consistency guarantees.

## Testing Your Configuration

<Card title="Test in Playground" icon="flask" href="https://playground.layerswap.io">
  Experiment with the configuration options in real-time before implementing in your application.
</Card>