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

# Customize the Velora Widget

> Pick a theme, follow the user's system preference, and understand how the widget's CSS is scoped.

The widget exposes a single visual control: a `theme` config field that switches between bundled light and dark themes.

## Set a theme

```tsx theme={null}
<Widget config={{ theme: "light" }} />
<Widget config={{ theme: "dark" }} />
<Widget />                              // follows system preference
```

`theme` accepts the `WidgetTheme` type: `"light" | "dark"`.

If you omit `theme`, the widget reads the user's OS preference via `prefers-color-scheme` and updates live when the preference changes.

## Switch themes at runtime

The theme is a controlled prop. Pass a new value any time to switch.

```tsx theme={null}
import { useState } from "react";
import { Widget, type WidgetTheme } from "@velora-dex/widget";

export function ThemedWidget() {
  const [theme, setTheme] = useState<WidgetTheme>("light");

  return (
    <>
      <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
        Toggle theme
      </button>
      <Widget config={{ theme }} />
    </>
  );
}
```

## CSS scoping

The widget is built with Tailwind v4 and scopes all CSS variables under the `.velora-widget` class. That means:

* The widget's styles don't leak into the rest of your app.
* Your app's global styles don't bleed into the widget either. Selectors targeting bare elements (`a`, `button`, `input`) inside the widget's DOM tree will still apply, but the widget's own variables take precedence within its root.

## Stylesheet auto-injection

The compiled stylesheet is auto-injected when you `import { Widget }`. No `.css` import required.

```tsx theme={null}
import { Widget } from "@velora-dex/widget";
// Stylesheet injected; nothing else needed.
```

If your bundler strips side-effect imports aggressively (rare but possible with aggressive `treeshake`), force-include the stylesheet:

```tsx theme={null}
import "@velora-dex/widget/styles.css";
```

## Related pages

* [Configure](/widget/configure) — every other config option.
* [Compatibility](/widget/compatibility) — Tailwind / bundler caveats.