Layerswap Docs

Theme reference

Overview

Theme Type Definition

Border Radius

Header Customization

Card Background Style

Layout Options

Hide Powered By

Complete Configuration Example

CSS Custom Properties

Testing Your Configuration

Test in Playground

Overview

Theme Type Definition

Border Radius

Header Customization

Card Background Style

Layout Options

Hide Powered By

Complete Configuration Example

CSS Custom Properties

Testing Your Configuration

Test in Playground

​Overview

​Theme Type Definition

​Border Radius

​Header Customization

​Card Background Style

​Layout Options

​Hide Powered By

​Complete Configuration Example

​CSS Custom Properties

​Testing Your Configuration

Test in Playground

Overview

Theme Type Definition

Border Radius

Header Customization

Card Background Style

Layout Options

Hide Powered By

Complete Configuration Example

CSS Custom Properties

Testing Your Configuration

Available Options

Hide Tabs

Hide Wallets

Complete Header Example

Basic Transparent Background

Glassmorphism Effect

Custom Gradient

With Shadow

Start here

Configuration

Production

Guides & tools

Self-bundled Widget

Available Options

Hide Menu

Hide Tabs

Hide Wallets

Complete Header Example

Basic Transparent Background

Glassmorphism Effect

Custom Gradient

With Shadow

​Available Options

​Hide Menu

​Hide Tabs

​Hide Wallets

​Complete Header Example

​Basic Transparent Background

​Glassmorphism Effect

​Custom Gradient

​With Shadow

Available Options

Hide Menu

Hide Tabs

Hide Wallets

Complete Header Example

Basic Transparent Background

Glassmorphism Effect

Custom Gradient

With Shadow

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.

The complete theme configuration type:

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.

Controls the roundness of corners for cards, buttons, and other UI elements throughout the widget.

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

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

object

Configuration object for widget header visibility options. Control which elements appear in the widget header.

boolean

Hide the menu button in the widget header. Set to true to remove the menu icon.

header: {
  hideMenu: true
}

boolean

Hide the tab switcher (swap / cex / deposit) in the widget header. Set to true to lock users into a specific flow.

header: {
  hideTabs: true
}

When hideTabs is true, users can only access the flow specified in initialValues.defaultTab. See Initial values & flows.

boolean

Hide the wallet connection display in the widget header. Set to true to remove the wallet indicator.

header: {
  hideWallets: true
}

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.

React.CSSProperties

Custom CSS styles for card backgrounds. Accepts any valid React CSS properties, enabling transparent backgrounds, blur effects, borders, and more.

cardBackgroundStyle: {
  backgroundColor: "transparent"
}

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

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)"
}

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

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.

boolean

Render the widget in its wide layout. Useful when the widget is the main content of a page rather than a compact embed.

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).

string

Logo accent color as an RGB triple string (e.g. '255, 50, 114').

boolean

Remove the “Powered by Layerswap” branding from the widget footer. Set to true to hide the attribution.

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

Here’s a complete example combining all configuration options:

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} />;
}

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.

Experiment with the configuration options in real-time before implementing in your application.

'medium'

'extraLarge'

'default'