Theming
Explore themes, customize their styles, and use design tokens
Using a theme
StellarAdmin includes all the standard shadcn themes, as well as 7 custom themes designed exclusively for StellarAdmin. Include a theme in your application by adding a reference to the theme's stylesheet in following format.
When installing StellarAdmin Tag Helpers, you must include a theme stylesheet. None of the Tag Helpers will render correctly without one.
<link rel="stylesheet" href="/_content/StellarAdmin.TagHelpers/<theme-stylesheet>" asp-append-version="true"/>Observatory is the default used throughout this documentation and a recommended starting point for new applications. It pairs cool neutral surfaces with blue accents in light mode and cyan accents in dark mode. Include it with:
<link rel="stylesheet" href="/_content/StellarAdmin.TagHelpers/stellar-admin.observatory.css" asp-append-version="true"/>Available themes
You can preview all the available themes in the example below, which has a good cross-section of the various Tag Helpers. All of the Tag Helper examples also allow you to select a theme in the preview.
StellarAdmin themes
The following themes were designed specifically for StellarAdmin. Each theme prefers the fonts listed below to give it its original character, and includes native font fallbacks. You will find code examples to include each theme below the table.
| Theme | Stylesheet | Optional fonts |
|---|---|---|
| Aurora | stellar-admin.aurora.css | Archivo (400/500/600) and IBM Plex Mono (400/500) |
| Concourse | stellar-admin.concourse.css | Source Sans 3 (400/500/600/700) and IBM Plex Mono (400/500) |
| Ice | stellar-admin.ice.css | IBM Plex Sans (400/500/600) and JetBrains Mono (400/500/700) |
| Ledger | stellar-admin.ledger.css | Lexend (300/400/500/600/700) and JetBrains Mono (400/500) |
| Meridian | stellar-admin.meridian.css | Instrument Sans (600), Work Sans (400/500/600), and JetBrains Mono (400/500) |
| Observatory | stellar-admin.observatory.css | IBM Plex Sans (400/500/600) and IBM Plex Mono (400/500) |
| Parallax | stellar-admin.parallax.css | Space Grotesk (400/500/600) and JetBrains Mono (400/500) |
The fonts are optional. Feel free to exclude it if you want to improve performance and avoid potential layout shift.
<!-- Optional Google Fonts. Exclude these to improve performance and avoid potential layout shift -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
<!-- Required StellarAdmin theme stylesheet -->
<link rel="stylesheet" href="/_content/StellarAdmin.TagHelpers/stellar-admin.aurora.css" asp-append-version="true">The Google Fonts display parameter controls how text appears while fonts load.
| Parameter | What your app's users experience |
|---|---|
display=auto | Their browser decides whether text appears immediately or waits for fonts. Use an explicit option below for more predictable behaviour. |
display=block | Button labels, navigation and table text may briefly be invisible while fonts load. Usually a poor choice for StellarAdmin apps because users must wait to read the interface. |
display=swap | Users can read the interface immediately; it switches to the theme's preferred fonts when loaded. Used by our demos, but labels and table content may shift as fonts change. |
display=fallback | Users see readable text after a very brief wait, with only a short window for a font change. Choose this to limit shifts while users work; slow connections may keep native fonts for that page view. |
display=optional | Users get native fonts unless the preferred fonts are ready almost immediately, avoiding a later font change. Choose this when keeping forms and tables stable matters more than matching the theme's typography. |
Shadcn themes
The shadcn themes use a shadcn. prefix in the name. We picked optional fonts that work well with each theme to give it a bit of character and stand out from the other shadcn themes. These fonts are completely optional and the themes will fall back to system fonts if you do not load them.
| Theme | Stylesheet | Optional fonts |
|---|---|---|
| Luma | stellar-admin.shadcn.luma.css | Inter (400–700) |
| Lyra | stellar-admin.shadcn.lyra.css | JetBrains Mono (400–700) |
| Maia | stellar-admin.shadcn.maia.css | Figtree (400–700) |
| Mira | stellar-admin.shadcn.mira.css | Inter (400–700) |
| Nova | stellar-admin.shadcn.nova.css | Geist (400–700) |
| Rhea | stellar-admin.shadcn.rhea.css | Inter (400–700) |
| Sera | stellar-admin.shadcn.sera.css | Noto Sans (body, 400–700) and Playfair Display (headings, 400–700) |
| Vega | stellar-admin.shadcn.vega.css | Inter (400–700) |
The fonts are optional. Feel free to exclude it if you want to improve performance and avoid potential layout shift.
<!-- Optional Google Fonts. Exclude these to improve performance and avoid potential layout shift -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap">
<!-- Required StellarAdmin theme stylesheet -->
<link rel="stylesheet" href="/_content/StellarAdmin.TagHelpers/stellar-admin.shadcn.luma.css" asp-append-version="true">Customizing a theme
Colors and radius in theme stylesheets are controlled with CSS variables. To customize one of the existing themes, you can override these variables. Consider the card example below.
By updating the variables to change the font and colors, we can achieve a completely different look.
The theme customization above was achieved by overriding the variables after importing the theme stylesheet.
<!DOCTYPE html>
<html lang="en">
<head>
...
<link rel="stylesheet" href="/_content/StellarAdmin.TagHelpers/stellar-admin.observatory.css" asp-append-version="true"/>
<!-- Import additional font used by the style override -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap" rel="stylesheet">
<!-- override the variable after importing the StellarAdmin stylesheet -->
<style>
:root {
--font-sans: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
--font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
--background: oklch(0.9784 0.0042 92);
--foreground: oklch(0.24 0.008 85);
--card: oklch(0.992 0.003 92);
--card-foreground: oklch(0.24 0.008 85);
--popover: oklch(0.992 0.003 92);
--popover-foreground: oklch(0.24 0.008 85);
--primary: oklch(0.6725 0.1362 42);
--primary-foreground: oklch(0.988 0.004 92);
--secondary: oklch(0.9451 0.0089 92);
--secondary-foreground: oklch(0.30 0.009 85);
--muted: oklch(0.9451 0.0089 92);
--muted-foreground: oklch(0.52 0.012 88);
--accent: oklch(0.925 0.018 80);
--accent-foreground: oklch(0.30 0.009 85);
--destructive: oklch(0.55 0.19 27);
--destructive-foreground: oklch(0.988 0.004 92);
--border: oklch(0.89 0.015 92);
--input: oklch(0.865 0.019 92);
--ring: oklch(0.6725 0.1362 42);
--chart-1: oklch(0.6725 0.1362 42);
--chart-2: oklch(0.63 0.07 130);
--chart-3: oklch(0.75 0.10 82);
--chart-4: oklch(0.51 0.07 55);
--chart-5: oklch(0.70 0.025 90);
--sidebar: oklch(0.9451 0.0089 92);
--sidebar-foreground: oklch(0.24 0.008 85);
--sidebar-primary: oklch(0.6725 0.1362 42);
--sidebar-primary-foreground: oklch(0.988 0.004 92);
--sidebar-accent: oklch(0.9784 0.0042 92);
--sidebar-accent-foreground: oklch(0.30 0.009 85);
--sidebar-border: oklch(0.88 0.016 92);
--sidebar-ring: oklch(0.6725 0.1362 42);
}
.dark {
--background: oklch(0.19 0.005 85);
--foreground: oklch(0.93 0.008 92);
--card: oklch(0.235 0.005 85);
--card-foreground: oklch(0.93 0.008 92);
--popover: oklch(0.235 0.005 85);
--popover-foreground: oklch(0.93 0.008 92);
--primary: oklch(0.705 0.13 42);
--primary-foreground: oklch(0.19 0.005 85);
--secondary: oklch(0.27 0.006 85);
--secondary-foreground: oklch(0.93 0.008 92);
--muted: oklch(0.27 0.006 85);
--muted-foreground: oklch(0.70 0.010 90);
--accent: oklch(0.31 0.012 70);
--accent-foreground: oklch(0.93 0.008 92);
--destructive: oklch(0.64 0.19 25);
--destructive-foreground: oklch(0.98 0.004 92);
--border: oklch(0.31 0.006 85);
--input: oklch(0.34 0.007 85);
--ring: oklch(0.705 0.13 42);
--chart-1: oklch(0.705 0.13 42);
--chart-2: oklch(0.68 0.075 130);
--chart-3: oklch(0.79 0.10 82);
--chart-4: oklch(0.58 0.075 55);
--chart-5: oklch(0.66 0.025 90);
--sidebar: oklch(0.22 0.005 85);
--sidebar-foreground: oklch(0.93 0.008 92);
--sidebar-primary: oklch(0.705 0.13 42);
--sidebar-primary-foreground: oklch(0.19 0.005 85);
--sidebar-accent: oklch(0.27 0.006 85);
--sidebar-accent-foreground: oklch(0.93 0.008 92);
--sidebar-border: oklch(0.31 0.006 85);
--sidebar-ring: oklch(0.705 0.13 42);
}
</style>
</head>
<body>
...
</body>
</html>
The CSS variables you can override are listed in the table below.
| Variable | Description |
|---|---|
--background / --foreground | Sets the base surface and text color of the application, which the page shell, page sections, and body text all inherit. |
--card / --card-foreground | Colors raised surfaces such as the Card component, dashboard panels, and settings panels, along with the content inside them. |
--popover / --popover-foreground | Colors overlay surfaces and their content, including Popover, DropdownMenu, ContextMenu, and similar floating components. |
--primary / --primary-foreground | Carries the brand color through prominent elements such as the default Button, selected states, badges, and active accents. |
--secondary / --secondary-foreground | Colors filled but quieter elements, such as secondary buttons and badges, that support the primary action without competing with it. |
--muted / --muted-foreground | Tones down surfaces and text that should recede, such as descriptions, placeholders, helper text, and empty states. |
--accent / --accent-foreground | Highlights elements as the user interacts with them, covering ghost buttons, hovered rows, highlighted menu entries, and selected items. |
--destructive | Signals danger and error, and is applied to destructive buttons, invalid form states, and destructive menu items. |
--border | Draws the borders and separators that divide cards, menus, tables, and page layout. |
--input | Styles the borders and surfaces of form controls such as Input, Textarea, Select, and other outline-style controls. |
--ring | Draws the focus ring that appears around buttons, inputs, checkboxes, menus, and any other focusable control. |
--chart-1 ... --chart-5 | Provides the default series palette used by charts and chart-driven dashboard blocks. |
--sidebar / --sidebar-foreground | Sets the surface and default text color of the Sidebar component and everything rendered inside it. |
--sidebar-primary / --sidebar-primary-foreground | Emphasizes the sidebar's most prominent elements, such as active items, icon tiles, badges, and calls to action. |
--sidebar-accent / --sidebar-accent-foreground | Marks hovered and selected sidebar elements, including menu entries, expanded items, and interactive rows. |
--sidebar-border | Draws the borders and separators inside the sidebar, such as those around headers and between groups. |
--sidebar-ring | Draws the focus ring around controls inside the sidebar. |
--font-sans / --font-mono | Sets the body and monospace font stacks. |
--sa-sera-font-display | Sets Sera’s heading font stack. |
--radius | Defines the base corner radius from which the radius-* variables are derived, shaping cards, inputs, buttons, and popovers. |
Using the design tokens in your own app
StellarAdmin Tag Helpers apply the theme styles to all the Tag Helpers. However, sometime you may also want to use the same colors in other parts of your application. For example, you may want to use the primary background color on an element. Your first thought may be to simply use the Tailwind CSS bg-primary token.
<div class="bg-primary">...</div>The above will likely not work because your own Tailwind configuration has not declared the correct theme variables.
To fix this, you can copy the theme-tokens.css file from StellarAdmin Tag Helpers into your project and import it from your Tailwind entry stylesheet:
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme) theme(inline reference);
@import "./theme-tokens.css" theme(reference);
@import "tailwindcss/utilities.css" layer(utilities);
@theme reference {
--font-sans: sans-serif;
--font-mono: monospace;
}The StellarAdmin theme stylesheet already includes Tailwind's preflight styles, the theme variables, and all the component styles, so your own build only needs to generate utility classes. A plain @import "tailwindcss" would output preflight and Tailwind's default theme variables again, such as --font-sans, and these override the theme's values whenever your stylesheet is linked after the StellarAdmin theme stylesheet. Importing the theme files as references avoids this, so the order of the stylesheet links no longer matters. The @theme reference block ensures font-sans and font-mono use the theme's fonts rather than Tailwind's defaults.
Once you do this, those design tokens will be used in your own Tailwind CSS configuration and you will have utility classes such as bg-primary, bg-secondary, text-primary-foreground, bg-card, etc. available to use in your own application. This will also ensure that your own application code will adapt to StellarAdmin theme changes and customizations.
Menu surfaces
Floating menus (such as the Dropdown Menu content and sub-menus) have three application-wide appearance settings, configured once in Program.cs by chaining ConfigureMenu off AddTagHelpers():
builder.Services.AddStellarAdmin()
.AddTagHelpers()
.ConfigureMenu(menu =>
{
menu.Color = MenuColor.Inverted;
menu.Appearance = MenuAppearance.Translucent;
menu.Accent = MenuAccent.Bold;
});Prop
Type
The defaults apply without calling ConfigureMenu. Call it only to change them.