Method Standalone Themes

Standalone Themes

Create completely independent themes with no dependencies on base styles or JavaScript.

Overview

Standalone themes give you complete control over every aspect of the Swagger UI appearance. They don't load base styles (common.css) or JavaScript features (ui.js), allowing you to build entirely custom designs from scratch.

Warning

Standalone themes cannot use advanced features or theme switcher. For most use cases, Theme Classes or Embedded Files are recommended.

What Are Standalone Themes?

Standalone themes:

• ✅ Don't load common.css (base theme styles)
• ✅ Don't load ui.js (JavaScript features)
• ✅ Give complete control over every aspect
• ✅ Start from scratch - no inherited styles

Creating a Standalone Theme

Naming Convention: Include "standalone" (case-insensitive) in the beginning of the CSS filename.

✅ standalone.custom.css

Coexisting with Regular Themes

You can have both standalone and regular versions of the same theme:

Folder Structure:

SwaggerThemes/
├── corporate.css              ← Regular (inherits base)
├── standalone.corporate.css   ← Standalone (independent)
├── dark.css                   ← Regular
└── standalone.dark.css        ← Standalone

Exact Matching:

// Loads standalone version (independent, no features)
app.UseSwaggerUI(assembly, "standalone.corporate.css", options => { });

// Loads regular version (inherits base, supports features)
app.UseSwaggerUI(assembly, "corporate.css", options => { });

The discovery system uses exact filename matching, so:

• Searching for "corporate.css" will NOT match "standalone.corporate.css" ✅
• Searching for "standalone.corporate.css" will NOT match "corporate.css" ✅

Tip

See Custom Themes - Regular vs Standalone Variants for detailed comparison and use cases.

Usage

var assembly = Assembly.GetExecutingAssembly();

// Swashbuckle
app.UseSwaggerUI(assembly, "standalone.custom.css", options => { });

// NSwag
app.UseSwaggerUi(assembly, "standalone.custom.css", settings => { });

Important Limitations

Warning

Standalone themes cannot:

• ❌ Use advanced features (pinnable topbar, back-to-top, etc.)
• ❌ Work with theme switcher (lacks required JavaScript)
• ❌ Inherit from Theme base class (use direct assembly loading)
• ❌ Access base theme CSS variables
• ❌ Load common.css or ui.js

You must implement everything from scratch!

Why no theme switcher? Standalone themes lack the JavaScript (ui.js) and common CSS (common.css) required for runtime theme switching.

File Structure

YourProject/
├── SwaggerThemes/
│   └── standalone.custom.css
└── Program.cs

Set the CSS file as Embedded Resource in your project.

Minification

You can use minified CSS files for better performance. The library does not automatically minify your CSS - you need to create minified versions yourself.

File naming:

SwaggerThemes/
├── standalone.corporate.css          ← Development version
└── standalone.corporate.min.css      ← Minified for production

Usage:

var assembly = Assembly.GetExecutingAssembly();

// Use minified version in production
var cssFile = builder.Environment.IsDevelopment() 
    ? "standalone.corporate.css" 
    : "standalone.corporate.min.css";

app.UseSwaggerUI(assembly, cssFile, options => { });

Creating minified files:

Use tools like:

• csso-cli: csso standalone.corporate.css -o standalone.corporate.min.css
• PostCSS + cssnano
• Online tools: CSS Minifier

Standalone vs Regular Theme Variants

Maintain both standalone and regular versions of the same theme side-by-side.

When to use both variants:

Regular Version (corporate.css)

Use when you want:

• ✅ Advanced features (sticky operations, pinnable topbar, etc.)
• ✅ Inherits base styles and variables
• ✅ Works with theme switcher
• ✅ Smaller file size
• ✅ Automatic updates from library improvements

Standalone Version (standalone.corporate.css)

Use when you need:

• ✅ Maximum compatibility
• ✅ No dependencies on library JavaScript/CSS
• ✅ Complete control over all styles
• ✅ Export to non-ASP.NET environments
• ✅ Guaranteed stability (no inheritance changes)

Learn more about regular themes with embedded files.

Next Steps

• Use Theme Classes - Full features with type-safety
• Use Embedded Files - Simpler setup with full features
• View CSS Variables - Not available in standalone, but useful reference
• View Advanced Options - Not available for standalone

---

← Custom Themes Overview