# Openfort UI Customization

This page covers the `uiConfig` options that control **how the wallet looks** — theme, colors, fonts, logo, custom components, and visual layout. For **what the wallet does** (authentication, recovery, funding, behavior), see [Configuration](/docs/products/embedded-wallet/react/ui/configuration).

<OpenfortThemePlayground />

:::info\[Ethereum]
You cannot log in with external wallets (MetaMask, WalletConnect, etc.) unless you add [@openfort/react/wagmi](/docs/products/embedded-wallet/javascript/smart-wallet/libraries#using-openfortwagmi-with-openfortreact).
:::

## Theme

Pick a built-in theme with `theme` and the light/dark mode with `mode` (both default to `auto`):

* `theme`: `auto` · `web95` · `retro` · `soft` · `midnight` · `minimal` · `rounded` · `nouns`
* `mode`: `auto` · `light` · `dark`

```jsx
<OpenfortProvider
  publishableKey="YOUR_OPENFORT_PUBLISHABLE_KEY"
  // ... other props
  uiConfig={{ // [!code focus]
    theme: "midnight", // [!code focus]
    mode: "dark", // [!code focus]
  }} // [!code focus]
>
  {/* Your app here */}
</OpenfortProvider>
```

## Custom theme

Edit fonts, colors, and other styling with `customTheme`. CSS custom properties use the `--ck-` prefix. Openfort UI theming is inspired by ConnectKit — see the [ConnectKit docs](https://docs.family.co/connectkit/customization) for the full list of variables.

```jsx
<OpenfortProvider
  publishableKey="YOUR_OPENFORT_PUBLISHABLE_KEY"
  // ... other props
  uiConfig={{ // [!code focus]
    theme: "midnight", // [!code focus]
    customTheme: { // [!code focus]
      '--ck-font-family': 'monospace', // [!code focus]
      '--ck-color-background': '#ccc', // [!code focus]
    }, // [!code focus]
  }} // [!code focus]
>
  {/* Your app here */}
</OpenfortProvider>
```

## Custom components

Bring your own components for parts of the UI:

* `logo`: The logo shown in the wallet (`React.ReactNode` — a JSX element).
* `customAvatar`: Custom avatar component. A `React.FC<CustomAvatarProps>` where `CustomAvatarProps` has `address` (hex string), `ensName`, `ensImage` (optional strings), and required `size` and `radius` (numbers). Pass a component function, not a ReactNode.
* `customPageComponents`: Replace specific modal pages with your own components (see below).

### Custom pages

Replace specific pages in the Openfort modal with your own components using `customPageComponents`. Currently the following route can be customized:

* `connected` — the profile/connected page shown after authentication (shown regardless of chain type).

```tsx
import { OpenfortProvider } from '@openfort/react';

function CustomConnectedPage() {
  return (
    <div style={{ padding: '16px' }}>
      <h2>My Profile</h2>
      <p>This is a custom profile page.</p>
    </div>
  );
}

function App() {
  return (
    <OpenfortProvider
      publishableKey="YOUR_KEY"
      uiConfig={{
        customPageComponents: {
          connected: <CustomConnectedPage />,
        },
      }}
    >
      {/* Your app */}
    </OpenfortProvider>
  );
}
```

## Visual options

Toggles that change how the modal looks and feels. All are chain-agnostic unless noted.

| Option | What it does |
| --- | --- |
| `hideBalance` | Hide the balance in the wallet. |
| `hideTooltips` | Hide tooltips in the wallet. |
| `hideRecentBadge` | Hide the "recent" badge. |
| `truncateLongENSAddress` | Truncate long ENS addresses (Ethereum only). |
| `reducedMotion` | Reduce animation and motion. |
| `overlayBlur` | Blur intensity applied to the background when the modal is open (`number`). |
| `avoidLayoutShift` | Avoid layout shift when the modal opens by padding the body. |
| `embedGoogleFonts` | Embed the current theme's Google font. Does not work with custom themes. |

## Components

Standalone display components you can drop into your own UI.

### Avatar

Display a user avatar based on their address.

```tsx
import { Avatar } from '@openfort/react'

<Avatar address="0x1234..." />
```

| Prop | Type | Description |
|------|------|-------------|
| `address` | `string` | Wallet address used to generate the avatar. |
| `size` | `number` | Avatar size in pixels. |
| `className` | `string` | CSS class for custom styling. |

### ChainIcon

Display a chain/network icon.

```tsx
import { ChainIcon } from '@openfort/react'

<ChainIcon chainId={1} />
```

| Prop | Type | Description |
|------|------|-------------|
| `chainId` | `number` | Chain ID to display the icon for. |
| `size` | `number` | Icon size in pixels. |
| `className` | `string` | CSS class for custom styling. |

## More customization

If you want to customize your authentication further, use the [authentication hooks](/docs/products/embedded-wallet/react/auth).