CSS Customization
Theme CopilotKit components via CSS variables and class overrides.
using System.ClientModel;using System.Net.Http;using System.Text.Json.Serialization;using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;using Microsoft.AspNetCore.Http.Json;using Microsoft.Extensions.Options;using OpenAI;var builder = WebApplication.CreateBuilder(args);builder.Services.ConfigureHttpJsonOptions(options =>{ // Beautiful-chat types (shipped) + the full-column Sales/Flight/parity types // ported by the family slots. Both source-generated contexts are chained so // every feature agent's tool I/O serializes through the fast path. options.SerializerOptions.TypeInfoResolverChain.Add(BeautifulChatSerializerContext.Default); options.SerializerOptions.TypeInfoResolverChain.Add(SalesAgentSerializerContext.Default); // Serialize enum types as their member-name strings rather than numeric // ordinals (matches the Framework column's wire format). options.SerializerOptions.Converters.Add(new JsonStringEnumConverter());});builder.Services.AddAGUI();// STOPGAP: IHttpContextAccessor lets AimockHeaderPolicy read the current// request's forwarded x-* headers (stashed on HttpContext.Items by// AimockHeaderMiddleware) at outbound-LLM-call time. HttpContext flows across// the AG-UI SSE-pump ExecutionContext boundary, unlike a middleware-set// AsyncLocal. TODO(copilotkit-sdk-dotnet): migrate to SDK-level header propagation.builder.Services.AddHttpContextAccessor();var app = builder.Build();// STOPGAP: seed the static accessor the outbound header-forwarding policy reads// (the policy is created without DI, mirroring CvDiag.Logger).AimockHeaderPolicy.HttpContextAccessor = app.Services.GetRequiredService<IHttpContextAccessor>();// Forward D5/aimock x-* headers from incoming AG-UI requests to outgoing// OpenAI calls until the .NET SDK owns this propagation centrally.app.UseMiddleware<AimockHeaderMiddleware>();// CVDIAG: backend flap-observability emitter (plan unit L1-F; spec §3). OFF by// default (CVDIAG_BACKEND_EMITTER=on to arm). Seed the static singleton the// outbound LLM policy reads (created without DI), then register the// request-pipeline instrumentation AFTER AimockHeaderMiddleware so the forwarded// x-* correlation headers are already captured for this request.CvdiagBackend.Instance = new CvdiagBackend();app.UseMiddleware<CvdiagInstrumentationMiddleware>();var loggerFactory = app.Services.GetRequiredService<ILoggerFactory>();// CVDIAG: seed the static logger used by AimockHeaderPolicy (created without DI)// to emit the outbound-LLM header-forwarding breadcrumb.CvDiag.Logger = loggerFactory.CreateLogger("CvDiag");var jsonOptions = app.Services.GetRequiredService<IOptions<JsonOptions>>().Value.SerializerOptions;// Single shared OpenAIClient for the whole column. Built once via the harness// ApiKeyResolver (env OPENAI_API_KEY -> config OPENAI_API_KEY -> GitHubToken,// fail-fast for non-mock endpoints) so EVERY feature agent hits the same// upstream with the same credential resolution — no per-feature GitHubToken// dance. Threaded into each feature factory's ctor. See the W0 contract §1.var openAiClient = CreateOpenAiClient(builder.Configuration, loggerFactory.CreateLogger("Program"));// ── Root agentic-chat agent (the Sales pipeline agent) ──────────────────────// agentic-chat, chat-slots, chat-customization-css, prebuilt-{sidebar,popup},// frontend-tools{,-async}, headless-simple, shared-state-read, and the two// tool-rendering catch-all demos all proxy to this root agent via the shared// Next.js `copilotkit/` runtime route.var salesFactory = new SalesAgentFactory(builder.Configuration, openAiClient, jsonOptions, loggerFactory);app.MapAGUI("/", salesFactory.CreateSalesAgent());// ── D5 parity agents (one factory hosts the parity-feature surface) ─────────var d5ParityFactory = new D5ParityAgentFactory(openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/headless-complete", d5ParityFactory.CreateHeadlessCompleteAgent());app.MapAGUI("/voice", d5ParityFactory.CreateVoiceAgent());app.MapAGUI("/gen-ui-agent", d5ParityFactory.CreateGenUiAgent());app.MapAGUI("/gen-ui-tool-based", d5ParityFactory.CreateGenUiToolBasedAgent());app.MapAGUI("/shared-state-streaming", d5ParityFactory.CreateSharedStateStreamingAgent());app.MapAGUI("/readonly-state-agent-context", d5ParityFactory.CreateReadonlyStateAgentContext());app.MapAGUI("/tool-rendering", d5ParityFactory.CreateToolRenderingAgent(reasoning: false));app.MapAGUI("/tool-rendering-reasoning-chain", d5ParityFactory.CreateToolRenderingAgent(reasoning: true));// ── Interrupt agent (NOT-SUPPORTED, wired for parity) ───────────────────────// gen-ui-interrupt and interrupt-headless share this single backend; the// differentiation is on the frontend (in-chat picker vs. headless button grid).// Marked not_supported in manifest.yaml (skipped-incapable) pending a// @copilotkit/react-core resume-path fix — wired here so the column is 1:1.var interruptFactory = new InterruptAgentFactory(builder.Configuration, openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/interrupt-adapted", interruptFactory.CreateInterruptAgent());// ── Multimodal (raw MapPost — the AG-UI adapter rejects content arrays) ─────// Parses the request body directly and emits the small AG-UI SSE event subset// the chat UI needs for text streaming over a vision-capable chat client.app.MapPost("/multimodal", (HttpContext context) => MultimodalEndpoint.HandleAsync( context, salesFactory.CreateMultimodalChatClient(), loggerFactory.CreateLogger("MultimodalEndpoint")));// ── Beautiful Chat flagship demo (shipped) ──────────────────────────────────var beautifulChatFactory = new BeautifulChatAgentFactory( builder.Configuration, openAiClient, jsonOptions, loggerFactory.CreateLogger<BeautifulChatAgentFactory>());app.MapAGUI("/beautiful-chat", beautifulChatFactory.Create());// ── Agent Config (wraps a neutral inner agent in AgentConfigAgent) ──────────app.MapAGUI("/agent-config", salesFactory.CreateAgentConfigAgent());// ── Reasoning (reasoning-default + reasoning-custom share this backend) ─────app.MapAGUI("/reasoning", salesFactory.CreateReasoningAgent());// ── Declarative Gen UI (A2UI canonical BYOC) ────────────────────────────────var declarativeGenUiAgent = new DeclarativeGenUiAgent(builder.Configuration, openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/declarative-gen-ui", declarativeGenUiAgent.Create());// ── A2UI fixed-schema demo ──────────────────────────────────────────────────var a2uiFixedSchemaAgent = new A2uiFixedSchemaAgent(builder.Configuration, openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/a2ui-fixed-schema", a2uiFixedSchemaAgent.Create());// ── Open Generative UI — basic + advanced ───────────────────────────────────var openGenUiFactory = new OpenGenUiAgentFactory(openAiClient);app.MapAGUI("/open-gen-ui", openGenUiFactory.CreateAgent());var openGenUiAdvancedFactory = new OpenGenUiAdvancedAgentFactory(openAiClient);app.MapAGUI("/open-gen-ui-advanced", openGenUiAdvancedFactory.CreateAgent());// ── BYOC demos (hashbrown + json-render) ────────────────────────────────────var byocHashbrownFactory = new ByocHashbrownAgentFactory(openAiClient, loggerFactory);app.MapAGUI("/byoc-hashbrown", byocHashbrownFactory.CreateAgent());var byocJsonRenderFactory = new ByocJsonRenderAgentFactory(openAiClient, loggerFactory);app.MapAGUI("/byoc-json-render", byocJsonRenderFactory.CreateAgent());// ── MCP Apps demo ───────────────────────────────────────────────────────────var mcpAppsFactory = new McpAppsAgentFactory(openAiClient, loggerFactory);app.MapAGUI("/mcp-apps", mcpAppsFactory.CreateMcpAppsAgent());// ── In-app HITL demo (frontend tools + async HITL) ──────────────────────────var hitlInAppFactory = new HitlInAppAgentFactory(openAiClient, loggerFactory);app.MapAGUI("/hitl-in-app", hitlInAppFactory.CreateHitlInAppAgent());// ── In-chat HITL demo (useHumanInTheLoop) ───────────────────────────────────var hitlInChatFactory = new HitlInChatAgentFactory(openAiClient, loggerFactory);app.MapAGUI("/hitl-in-chat", hitlInChatFactory.CreateHitlInChatAgent());// ── Shared State (Read + Write) demo ────────────────────────────────────────var sharedStateReadWriteFactory = new SharedStateReadWriteAgentFactory(openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/shared-state-read-write", sharedStateReadWriteFactory.CreateAgent());// ── Sub-Agents demo (supervisor delegates to research/writing/critique) ─────var subagentsFactory = new SubagentsAgentFactory(openAiClient, loggerFactory, jsonOptions);app.MapAGUI("/subagents", subagentsFactory.CreateAgent());app.MapGet("/health", () => Results.Ok(new { status = "ok" }));await app.RunAsync();static OpenAIClient CreateOpenAiClient(IConfiguration configuration, ILogger logger){ // Use the shared resolver so the primary OpenAI client and the secondary // tool-calling HTTP client (A2uiSecondaryToolCaller) agree on which upstream // endpoint to hit (see ApiKeyResolver for the env/config precedence and the // non-mock fail-fast). var endpoint = ApiKeyResolver.ResolveEndpoint(configuration); var endpointEnv = Environment.GetEnvironmentVariable("OPENAI_BASE_URL"); var endpointConfig = configuration["OPENAI_BASE_URL"]; if (!string.IsNullOrEmpty(endpointEnv)) { logger.LogInformation("Using OpenAI endpoint from OPENAI_BASE_URL env: {Endpoint}", endpoint); } else if (!string.IsNullOrEmpty(endpointConfig)) { logger.LogInformation("Using OpenAI endpoint from configuration OPENAI_BASE_URL: {Endpoint}", endpoint); } else { logger.LogInformation("OPENAI_BASE_URL not set; using default OpenAI endpoint: {Endpoint}", endpoint); } var apiKey = ApiKeyResolver.ResolveApiKey(configuration, logger); return new OpenAIClient( new ApiKeyCredential(apiKey), AimockHeaderPolicy.CreateOpenAIClientOptions(endpoint));}public class WeatherInfo{ [JsonPropertyName("temperature")] public int Temperature { get; init; } [JsonPropertyName("conditions")] public string Conditions { get; init; } = string.Empty; [JsonPropertyName("humidity")] public int Humidity { get; init; } [JsonPropertyName("wind_speed")] public int WindSpeed { get; init; } [JsonPropertyName("feels_like")] public int FeelsLike { get; init; } [JsonPropertyName("city")] public string City { get; init; } = string.Empty;}public partial class Program { }[JsonSerializable(typeof(WeatherInfo))][JsonSerializable(typeof(BeautifulChatTodo))][JsonSerializable(typeof(List<BeautifulChatTodo>))][JsonSerializable(typeof(BeautifulChatFlight))][JsonSerializable(typeof(List<BeautifulChatFlight>))]internal partial class BeautifulChatSerializerContext : JsonSerializerContext{}What is this?#
CopilotKit has a variety of ways to customize the colors and structure of the Copilot UI components via plain CSS. You can:
- Override CopilotKit CSS variables to re-tint the whole UI
- Target the built-in class names (
.copilotKit...) for structural tweaks - Swap fonts per surface (messages, input, bubbles)
- Replace icons and labels via component props
If you need to change behavior, not just look, see slots or fully headless UI.
Scoping the theme#
The demo keeps all of its styling in a sibling theme.css file and applies it
only to the wrapper div holding <CopilotChat>. Importing the stylesheet from
the page module is enough; Next.js bundles it with the route:
import "./theme.css";Scoping every selector under a wrapper class keeps the overrides from leaking into the rest of the app.
CSS Variables (Easiest)#
The easiest way to change the colors used in the Copilot UI components is to override CopilotKit CSS variables. The demo sets them on the scope wrapper so they cascade into every nested chat component:
/* HALCYON palette — a private library at golden hour. The whole theme is * one warm parchment hue, one warm ink, and a deep copper ember used * sparingly so it actually reads as a signal. */.chat-css-demo-scope { --halcyon-paper: #f4efe6; --halcyon-paper-soft: #ece6d9; --halcyon-paper-elevated: #fbf8f2; --halcyon-card: #ffffff; --halcyon-rule: #d6cfbe; --halcyon-rule-strong: #aea48a; --halcyon-ink: #1a1714; --halcyon-ink-soft: #3d362e; --halcyon-ink-mute: #7a7468; --halcyon-ember: #c44a1f; --halcyon-ember-bright: #e45f2b; --halcyon-ember-soft: #f3d7c5; --halcyon-champagne: #98794a; --halcyon-display: "Instrument Serif", ui-serif, "Iowan Old Style", Georgia, serif; --halcyon-serif: "Fraunces", "Source Serif Pro", ui-serif, Georgia, "Times New Roman", serif; --halcyon-sans: "Inter Tight", ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; --halcyon-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace; --halcyon-shadow-soft: 0 1px 0 rgba(26, 23, 20, 0.04), 0 12px 32px -18px rgba(26, 23, 20, 0.18); --halcyon-shadow-ember: 0 1px 0 rgba(196, 74, 31, 0.18), 0 14px 36px -16px rgba(196, 74, 31, 0.42);}Once you've found the right variable, you can also apply the overrides inline
via the CopilotKitCSSProperties helper:
import { CopilotKitCSSProperties } from "@copilotkit/react-ui";
<div
style={
{
"--copilot-kit-primary-color": "#222222",
} as CopilotKitCSSProperties
}
>
<CopilotSidebar />
</div>Reference#
| CSS Variable | Description |
|---|---|
--copilot-kit-primary-color | Main brand/action color for buttons and interactive elements |
--copilot-kit-contrast-color | Color that contrasts with primary, used for text on primary elements |
--copilot-kit-background-color | Main page/container background color |
--copilot-kit-secondary-color | Secondary background for cards, panels, and elevated surfaces |
--copilot-kit-secondary-contrast-color | Primary text color for main content |
--copilot-kit-separator-color | Border color for dividers and containers |
--copilot-kit-muted-color | Muted color for disabled/inactive states |
--copilot-kit-shadow-sm / -md / -lg | Elevation shadows for subtle surfaces, cards, and modals |
Two token systems
The --copilot-kit-* variables above style the v1 component CSS
(@copilotkit/react-ui). The newer v2 components
(@copilotkit/react-core/v2) are Tailwind + shadcn-based and use a
separate set of design tokens. See v2 design
tokens below.
v2 Design Tokens (shadcn)#
The v2 components (@copilotkit/react-core/v2) ship a Tailwind v4 theme built
on the standard shadcn/ui token set. Instead of the --copilot-kit-*
variables, they read oklch color tokens that are scoped to
the [data-copilotkit] root and wired into Tailwind utilities through an
@theme inline block. This means you can re-skin the entire v2 UI by
overriding a handful of CSS custom properties. Every component picks the
change up automatically.
Override them on the [data-copilotkit] element (or any ancestor) the same way
you would in a shadcn project:
[data-copilotkit] {
--primary: oklch(0.55 0.22 264); /* accent / action color */
--primary-foreground: oklch(0.99 0 0); /* text on primary */
--background: oklch(1 0 0); /* surface background */
--foreground: oklch(0.145 0 0); /* primary text */
--muted: oklch(0.97 0 0); /* subtle backgrounds */
--border: oklch(0.922 0 0); /* dividers, outlines */
--radius: 0.625rem; /* global corner radius */
}
/* Dark mode is keyed off a `.dark` ancestor */
.dark [data-copilotkit] {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--border: oklch(0.269 0 0);
}Reference#
These are the most commonly overridden v2 tokens. Each light value has a
matching dark-mode value under .dark [data-copilotkit]. The full set
(popover, accent, destructive, chart, and sidebar variants) lives in
@copilotkit/react-core/v2/styles.css.
| Token | Description |
|---|---|
--background / --foreground | Base surface background and primary text color |
--primary / --primary-foreground | Accent/action color and the text rendered on top of it |
--secondary / --secondary-foreground | Secondary surfaces (cards, panels) and their text |
--muted / --muted-foreground | Subtle backgrounds and de-emphasized text |
--accent / --accent-foreground | Hover/active states and their text |
--border / --input / --ring | Divider/outline color, input borders, focus ring |
--destructive / --destructive-foreground | Error/danger color and its text |
--card / --popover (+ -foreground) | Elevated surface backgrounds and their text |
--sidebar-* | The sidebar's own background/foreground/border/ring set |
--radius | Base corner radius; --radius-sm/md/lg/xl derive from it |
oklch values
v2 tokens use the oklch() color space, which keeps perceived lightness
consistent across hues. You can still pass hsl(), rgb(), or hex; any
valid CSS color works.
Custom CSS#
The CopilotKit CSS is structured to allow customization via CSS classes. You can target specific pieces of the UI from your own stylesheet:
.copilotKitButton {
border-radius: 0;
}
.copilotKitMessages {
padding: 2rem;
}
.copilotKitUserMessage {
background: #007AFF;
}The demo's theme.css wraps every selector under .chat-css-demo-scope so
the overrides don't leak out. Here's the user message bubble block from
that file:
/* User message — a "transmission" in JetBrains Mono on a paper card. The * outer wrapper is the right-aligning flex column; we leave it transparent * and style the inner bubble (which uses cpk:bg-muted, hence we also * target the substring class as a stable hook). */.chat-css-demo-scope .copilotKitMessage.copilotKitUserMessage { background: transparent; padding: 0; border: none; box-shadow: none;}.chat-css-demo-scope .copilotKitMessage.copilotKitUserMessage > [class*="bg-muted"] { font-family: var(--halcyon-mono); font-size: 0.875rem; font-weight: 400; color: var(--halcyon-ink); background: var(--halcyon-paper-elevated); border: 1px solid var(--halcyon-rule); border-left: 2px solid var(--halcyon-ember); border-radius: 0; padding: 12px 16px 12px 18px; letter-spacing: -0.005em; line-height: 1.55; box-shadow: 0 1px 0 rgba(26, 23, 20, 0.03); position: relative;}/* A mono "→" marker before the user's text to read like a CLI prompt. */.chat-css-demo-scope .copilotKitMessage.copilotKitUserMessage > [class*="bg-muted"]::before { content: "→"; display: inline-block; margin-right: 10px; color: var(--halcyon-ember); font-weight: 500;}Reference#
| CSS Class | Description |
|---|---|
.copilotKitMessages | Main container for all chat messages |
.copilotKitMessage | Base class applied to every message bubble (user and assistant) |
.copilotKitInput | Text input container with typing area and send button |
.copilotKitUserMessage | Styling for user messages |
.copilotKitAssistantMessage | Styling for AI responses |
.copilotKitHeader | Top bar of chat window containing title and controls |
.copilotKitButton | Primary chat toggle button |
.copilotKitWindow | Root container defining overall chat window dimensions |
.copilotKitMarkdown | Styles for rendered markdown content |
.copilotKitCodeBlock | Code snippet container with syntax highlighting |
.copilotKitSidebar | Styles for sidebar chat mode |
.copilotKitPopup | Styles for popup chat mode |
Custom Fonts#
You can customize the fonts by updating the fontFamily property on the
relevant CopilotKit classes:
.copilotKitMessages {
font-family: "Arial, sans-serif";
}
.copilotKitInput {
font-family: "Arial, sans-serif";
}Custom Icons#
Customize icons by passing the icons prop to CopilotSidebar, CopilotPopup,
or CopilotChat:
<CopilotChat
icons={{
openIcon: <YourOpenIconComponent />,
closeIcon: <YourCloseIconComponent />,
}}
/>Custom Labels#
Customize all user-facing copy via the labels prop:
<CopilotChat
labels={{
welcomeMessageText: "Hello! How can I help you today?",
modalHeaderTitle: "My Copilot",
chatInputPlaceholder: "Ask me anything!",
}}
/>