> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/widget-integration/styling.md).

# Styling & Theming

The widget is built to feel native to your product. Theming is a **two-tier system**, applied in order of increasing priority:

1. **Theme mode** — pick light or dark.
2. **Component styles** — override individual brand colors and the width.

Component styles win over theme mode. Pass both, or just what you need.

## The `styles` object

```typescript
type SwapperStyles = {
  themeMode?: "light" | "dark";
  componentStyles?: ComponentStyles;
};
```

### Basic theme selection

```typescript
const styles = { themeMode: "dark" }; // or "light" (default)
```

### With overrides

```typescript
const styles = {
  themeMode: "dark",
  componentStyles: {
    primaryColor: "#FF6B35",
    backgroundColor: "#1A1A1A",
    surfaceColor: "#222222",
    textColor: "#E8E8E8",
    primaryButtonTextColor: "#FFFFFF",
    width: "100%",
  },
};
```

## `componentStyles` properties

| Property                 | Purpose                                             |
| ------------------------ | --------------------------------------------------- |
| **Layout**               |                                                     |
| `width`                  | Widget width (default `450px`).                     |
| **Brand & surfaces**     |                                                     |
| `primaryColor`           | Main brand color — buttons, links, primary accents. |
| `backgroundColor`        | Widget background.                                  |
| `surfaceColor`           | Cards and inputs.                                   |
| **Typography**           |                                                     |
| `textColor`              | Main text.                                          |
| `primaryButtonTextColor` | Text on primary buttons.                            |

## Applying styles

**Iframe SDK / modal / embed** — pass `styles` in the config, or update live:

```typescript
const swapper = new SwapperIframe({ /* ...config */, styles: { themeMode: "dark" } });

// change it later without reloading:
swapper.updateStyles({
  themeMode: "light",
  componentStyles: { primaryColor: "#836FFF" },
});
```

## Under the hood: CSS variables

Inside the widget, styles map to CSS custom properties applied at the widget root — `--swapper-primary-color`, `--swapper-background-color`, `--swapper-text-color`, `--swapper-width`, and friends — with dark mode toggled via a class. Passing `componentStyles` sets these for you.

## Modal chrome vs. widget theme

For the [modal](/widget-integration/modal-and-embed.md), `styles` themes the **widget content**, while `modalStyle` controls the **modal shell** (overlay color, modal radius, width/height, z-index). They're independent — style both to match your app.

{% hint style="info" %}
Set `width: "100%"` in `componentStyles` to let the widget fill a responsive container, then constrain the container itself in your layout.
{% endhint %}