Theming

The UI wire includes a flexible theming system based on CSS custom properties (variables). Customize colors, typography, spacing, and more.

Configuration

Pass a theme object to FluxKitProvider:

import { FluxKitProvider } from "@fluxkitdev/ui";

<FluxKitProvider
  apiUrl="http://localhost:3000"
  theme={{
    primaryColor: "#6366f1",
    secondaryColor: "#ec4899",
    backgroundColor: "#ffffff",
    surfaceColor: "#f8f9fa",
    textColor: "#1a1a1a",
    borderRadius: "8px",
    fontFamily: "Inter, system-ui, sans-serif",
    fontSize: "16px",
  }}
>
  {children}
</FluxKitProvider>

Theme Properties

Property	Default (Light)	Default (Dark)	Description
primaryColor	#6366f1	#818cf8	Primary brand color
secondaryColor	#ec4899	#f472b6	Secondary accent color
backgroundColor	#ffffff	#0f0f0f	Page background
surfaceColor	#f8f9fa	#1a1a1a	Card/surface background
textColor	#1a1a1a	#f0f0f0	Primary text color
mutedColor	#6b7280	#9ca3af	Muted/secondary text
borderColor	#e5e7eb	#374151	Border color
borderRadius	8px	8px	Default border radius
fontFamily	Inter, sans-serif	Inter, sans-serif	Base font family
fontSize	16px	16px	Base font size
successColor	#10b981	#34d399	Success state color
warningColor	#f59e0b	#fbbf24	Warning state color
errorColor	#ef4444	#f87171	Error state color

Dark Mode

Dark mode is supported out of the box. Use the useColorMode hook to toggle:

import { useColorMode } from "@fluxkitdev/ui";

function ThemeToggle() {
  const { colorMode, toggleColorMode } = useColorMode();

  return (
    <button onClick={toggleColorMode}>
      {colorMode === "dark" ? "Light Mode" : "Dark Mode"}
    </button>
  );
}

Set the default mode:

<FluxKitProvider
  apiUrl="http://localhost:3000"
  theme={{
    defaultColorMode: "dark",    // "light" | "dark" | "system"
  }}
>

CSS Custom Properties

All theme values are exposed as CSS custom properties for use in your own styles:

.my-component {
  color: var(--fk-text-color);
  background: var(--fk-surface-color);
  border: 1px solid var(--fk-border-color);
  border-radius: var(--fk-border-radius);
  font-family: var(--fk-font-family);
}

.my-button {
  background: var(--fk-primary-color);
  color: white;
}

Component-Level Overrides

Override styles for individual components using the sx prop:

import { Button, Card } from "@fluxkitdev/ui";

<Button
  sx={{
    backgroundColor: "#10b981",
    borderRadius: "999px",
    padding: "12px 24px",
  }}
>
  Custom Button
</Button>

<Card sx={{ border: "2px solid var(--fk-primary-color)" }}>
  Highlighted Card
</Card>

Extending the Theme

Create a reusable theme configuration:

// theme.ts
import type { ThemeConfig } from "@fluxkitdev/ui";

export const myTheme: ThemeConfig = {
  primaryColor: "#2563eb",
  secondaryColor: "#7c3aed",
  borderRadius: "12px",
  fontFamily: '"Poppins", sans-serif',
  defaultColorMode: "system",
};

import { FluxKitProvider } from "@fluxkitdev/ui";
import { myTheme } from "./theme";

<FluxKitProvider apiUrl="http://localhost:3000" theme={myTheme}>
  {children}
</FluxKitProvider>