Customize AGG UI

AGG UI is designed to be embedded in partner apps without forking components. The supported customization surface is:

CSS variables on the AGG root for brand, typography, radius, shadow, and z-index tokens
AggProvider config for theme mode, labels, formatting, feature flags, search wiring, and wallet actions
component className / classNames props for layout composition

Import @agg-build/ui/styles.css once, then load your app CSS after it. AGG defaults are low specificity, so :root overrides can work, and .agg-root overrides win because they are closer to the AGG UI tree.

Minimal integration

app/providers.tsx

import "@agg-build/ui/styles.css";
import "./agg-theme.css";

import { AggProvider, QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { createAggClient } from "@agg-build/sdk";
import type { ReactNode } from "react";

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
  wsUrl: "wss://ws.agg.market/ws",
});

const queryClient = new QueryClient();

export function Providers({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <AggProvider
        client={client}
        config={{
          general: {
            locale: "en-US",
            theme: "light",
            rootClassName: "acme-agg-theme",
          },
          features: {
            enableAnimations: true,
            enableLiveUpdates: true,
            enableGradients: false,
            showFeesBreakdown: true,
          },
        }}
      >
        {children}
      </AggProvider>
    </QueryClientProvider>
  );
}

app/page.tsx

import { HomePage } from "@agg-build/ui/pages";

export default function Page() {
  return <HomePage withHeader />;
}

AggProvider renders an .agg-root wrapper around its children. If you pass general.rootClassName, that class is added to the same root so you can scope partner-specific branding without affecting other AGG embeds on the page.

Import order

Load AGG styles first and partner overrides second:

import "@agg-build/ui/styles.css";
import "./agg-theme.css";

Then put variables in your CSS:

agg-theme.css

.agg-root.acme-agg-theme {
  --agg-color-primary: #2563eb;
  --agg-color-primary-hover: #1d4ed8;
  --agg-color-secondary: #ffffff;
  --agg-color-secondary-hover: #f1f5f9;
  --agg-color-border: #cbd5e1;
  --agg-color-foreground: #0f172a;
  --agg-color-muted-foreground: #475569;
  --agg-color-on-primary: #ffffff;
  --agg-radius-md: 0.625rem;
  --agg-radius-full: 0.75rem;
  --agg-shadow-card: 0 8px 20px rgb(15 23 42 / 0.08);
}

Custom fonts

Set the AGG font token on .agg-root. This affects AGG typography utilities, primitives, pages, modals, and portaled surfaces.

Plain CSS

.agg-root {
  --agg-font-family-sans: "Your Font", ui-sans-serif, system-ui, sans-serif;
}

You can also set the token on :root; a value on .agg-root wins if both exist.

Next.js `next/font`

Expose the generated font variable on an ancestor, then map it into the AGG token.

app/layout.tsx

import { Inter } from "next/font/google";
import { Providers } from "./providers";
import "./globals.css";

const inter = Inter({
  subsets: ["latin"],
  variable: "--font-inter",
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.variable}>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

globals.css

.agg-root {
  --agg-font-family-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
}

Light and dark themes

general.theme controls the class and data attributes applied to .agg-root. If you ship custom dark tokens, match AGG’s dark selector shape so your values win in dark mode:

.dark .agg-root.acme-agg-theme:not(.light),
.agg-dark .agg-root.acme-agg-theme:not(.light),
.agg-root.acme-agg-theme.dark,
.agg-root.acme-agg-theme[data-agg-theme="dark"] {
  --agg-color-primary: #8fb4ff;
  --agg-color-primary-hover: #b4ccff;
  --agg-color-secondary: #0b1220;
  --agg-color-secondary-hover: #172036;
  --agg-color-border: #334155;
  --agg-color-foreground: #e2e8f0;
  --agg-color-muted-foreground: #94a3b8;
  --agg-color-on-primary: #121214;
  --agg-shadow-card: 0 10px 28px rgb(2 6 23 / 0.45);
}

Gradients

Keep semantic colors and gradient definitions separate. features.enableGradients controls whether branded surfaces resolve to flat primary colors or gradient tokens.

<AggProvider
  client={client}
  config={{
    features: {
      enableGradients: true,
    },
  }}
>
  <HomePage />
</AggProvider>

.agg-root.acme-agg-theme {
  --agg-gradient-brand: linear-gradient(90deg, #2563eb, #4f46e5);
  --agg-gradient-brand-hover: linear-gradient(90deg, #1d4ed8, #4338ca);
}

.dark .agg-root.acme-agg-theme:not(.light),
.agg-dark .agg-root.acme-agg-theme:not(.light),
.agg-root.acme-agg-theme.dark,
.agg-root.acme-agg-theme[data-agg-theme="dark"] {
  --agg-gradient-brand: linear-gradient(90deg, #8fb4ff, #c084fc);
  --agg-gradient-brand-hover: linear-gradient(90deg, #b4ccff, #d8b4fe);
}

Public theme tokens

Set these on .agg-root or .agg-root.<your-rootClassName>.

Token	Usage
`--agg-color-primary`	Primary CTA color and emphasis states
`--agg-color-primary-hover`	Primary action hover color
`--agg-color-secondary`	Card, popover, modal, and control surfaces
`--agg-color-secondary-hover`	Neutral hover and selected surfaces
`--agg-color-border`	Borders and separators
`--agg-color-foreground`	Primary text and icon foreground
`--agg-color-muted-foreground`	Secondary text, metadata, and helper labels
`--agg-color-on-primary`	Text and icons on branded filled surfaces
`--agg-color-success`	Positive status and bid-side color
`--agg-color-warning`	Warning status
`--agg-color-error`	Error status and ask-side color
`--agg-color-overlay`	Modal and drawer overlay color
`--agg-gradient-brand`	Branded gradient fill
`--agg-gradient-brand-hover`	Branded gradient hover fill
`--agg-font-family-sans`	Base AGG UI font family
`--agg-font-size-2xs` through `--agg-font-size-4xl`	Typography size scale
`--agg-line-height-3`, `--agg-line-height-14`, `--agg-line-height-4` through `--agg-line-height-10`, `--agg-line-height-base`	Typography line-height scale
`--agg-font-weight-normal`, `--agg-font-weight-medium`, `--agg-font-weight-semibold`, `--agg-font-weight-bold`	Typography weight scale
`--agg-radius-sm`, `--agg-radius-md`, `--agg-radius-lg`, `--agg-radius-xl`, `--agg-radius-2xl`, `--agg-radius-full`	Radius scale
`--agg-shadow-card`, `--agg-shadow-popover`, `--agg-shadow-modal`	Elevation tokens
`--agg-z-index-dropdown`, `--agg-z-index-overlay`, `--agg-z-index-modal`, `--agg-z-index-toast`, `--agg-z-index-tooltip`	Dropdown, overlay, modal, toast, and tooltip layering

Avoid overriding bridge tokens such as --color-agg-*, --text-agg-*, and --font-agg-sans directly. They are generated from the public --agg-* tokens.

Copy and labels

Use general.labels when you need to change user-facing text. Label overrides are deep-merged with AGG defaults, so you only provide the keys you want to replace.

<AggProvider
  client={client}
  config={{
    general: {
      labels: {
        common: {
          retry: "Try again",
        },
        auth: {
          signIn: "Sign in to Acme",
          deposit: "Add funds",
        },
        eventList: {
          emptyTitle: "No markets match your filters",
        },
      },
    },
  }}
>
  <HomePage />
</AggProvider>

Use labels for product copy. Use CSS variables for visual styling. Use component props for data, callbacks, and layout.

Formatting

Override formatting functions when your app needs a different locale, currency presentation, or date style.

const usdCompact = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  notation: "compact",
  maximumFractionDigits: 1,
});

<AggProvider
  client={client}
  config={{
    general: {
      locale: "en-US",
    },
    formatting: {
      formatCompactCurrency: (value) => usdCompact.format(value),
    },
  }}
>
  <HomePage />
</AggProvider>;

Odds display

formatPercent and formatPrice are two renderings of the same number — both receive a probability between 0 and 1. Discovery surfaces (event tiles, search results, charts) use formatPercent; price surfaces (order book, event page outcome chips, place-order, positions) use formatPrice. To show a single odds convention app-wide, set both to the same function:

// Decimal odds: 0.62 -> "1.61"
const toDecimalOdds = (probability: number) => (1 / probability).toFixed(2);

<AggProvider
  client={client}
  config={{
    formatting: {
      formatPercent: toDecimalOdds,
      formatPrice: toDecimalOdds,
    },
  }}
>
  <HomePage />
</AggProvider>;

formatPrice is optional. Leave it unset to keep the default cents rendering (62.5¢). Two values deliberately stay on the built-in formatters even when formatPrice is set, because neither is a price: the order book spread (a difference between two prices, always in cents) and position PnL percentages.

Layout and slots

Use className / classNames for layout composition, not deep CSS selectors.

import { HomePage } from "@agg-build/ui/pages";

export function MarketHome() {
  return (
    <HomePage
      withHeader={false}
      classNames={{
        root: "min-h-screen",
        header: "border-b border-slate-200 bg-white/90 backdrop-blur",
        tabs: "mx-auto w-full max-w-6xl px-6",
        sections: "mx-auto w-full max-w-6xl px-6 py-8 gap-8",
      }}
    />
  );
}

Prefer token overrides for colors, fonts, radius, shadows, and other repeated visual decisions. Use slot class names for spacing, containment, sticky behavior, or one-off layout requirements.

Troubleshooting

My custom font does not apply

Make sure @agg-build/ui/styles.css is imported before your app CSS, and set --agg-font-family-sans on .agg-root. With next/font, put the generated font variable on an ancestor of AggProvider.

Dark mode falls back to AGG defaults

Add a dark-mode override block using AGG’s selector shape. Light tokens and dark tokens are separate.

My Tailwind classes do not restyle AGG internals

AGG internals use AGG token utilities. Override --agg-* variables for global theming, and use documented className / classNames props for layout slots.

Storybook Customization

Interactive token guide and live component catalog.

Theme Studio

Import a URL, inspect extracted brand tokens, and export CSS.

Setup Guide

Provider setup for SDK, hooks, UI components, and auth.

Components Overview

Curated references for pages, trading surfaces, events, and auth UI.

Getting Started

Components

REST API

WebSocket Protocol

Authentication

Account

Funding & Execution

Webhooks

Discovery

Real-Time Data

Releases

Customize UI

Customize AGG UI

Minimal integration

Import order

Custom fonts

Plain CSS

Next.js `next/font`

Light and dark themes

Gradients

Public theme tokens

Copy and labels

Formatting

Odds display

Layout and slots

Troubleshooting

Storybook Customization

Theme Studio

Setup Guide

Components Overview

​Customize AGG UI

​Minimal integration

​Import order

​Custom fonts

​Plain CSS

​Next.js next/font

​Light and dark themes

​Gradients

​Public theme tokens

​Copy and labels

​Formatting

​Odds display

​Layout and slots

​Troubleshooting

​Related tools

Storybook Customization

Theme Studio

Setup Guide

Components Overview

Customize AGG UI

Minimal integration

Import order

Custom fonts

Plain CSS

Next.js `next/font`

Light and dark themes

Gradients

Public theme tokens

Copy and labels

Formatting

Odds display

Layout and slots

Troubleshooting

Related tools