Skip to content

CSS Variables

Jump to bottom
teociaps edited this page Nov 27, 2025 · 6 revisions

Customize your Swagger UI theme appearance using predefined CSS variables. All themes (except inline CSS and standalone themes) support these variables for fine-grained control over colors, spacing, and styling.

Overview

CSS variables allow you to:

  • Customize colors without writing extensive CSS
  • Override defaults while keeping base theme structure
  • Maintain consistency across your application
  • Quick changes - modify one variable, update everywhere

How to Use CSS Variables

Add variables to your custom CSS file using the :root selector:

/* custom-theme.css */
:root {
  /* Override specific variables */
  --swagger-main-color: #ff6b35;
  --body-background-color: #1a1a2e;
  --topbar-background-color: #2c3e50;
}

Tip

You don't need to define all variables - only override the ones you want to change!

Variable Format

Placeholder Description Examples
<color> Any valid CSS color #fff, red, rgba(136, 170, 212, 0.5), hsla(0, 0%, 100%, 0.14), transparent
<image/svg> Image or SVG data URL url('data:image/svg+xml;charset=utf-8,<svg>...</svg>')

Available CSS Variables

Core Colors

--body-background-color: <color>; /* Main page background */
--swagger-main-color: <color>; /* Primary theme color */

Loading Indicator

--loading-container-border-color: <color>;
--loading-container-border-top-color: <color>;

Error Messages

--errors-wrapper-background-color: <color>;
--errors-wrapper-border-color: <color>;
--errors-wrapper-errors-color: <color>;

Topbar

--topbar-background-color: <color>;
--topbar-pinned-background-color: <color>; /* When pinned */
--topbar-pinned-shadow-color: <color>; /* Pin shadow */
--topbar-pin-icon-color: <color>; /* Pin button color */
--topbar-border-color: <color>; /* Bottom border */
--topbar-select-border-color: <color>;
--topbar-select-label-color: <color>;
--topbar-download-url-button-background-color: <color>;
--topbar-download-url-button-color: <color>;

Info Box

--swagger-info-link: <color>;
--swagger-info-link-hover: <color>;
--api-version-background-color: <color>;
--api-version-stamp-background-color: <color>;
--api-version-color: <color>;

Authorization

--auth-wrapper-background-color: <color>; /* Modal background */
--auth-wrapper-border-color: <color>; /* Modal border */
--auth-wrapper-box-shadow-color: <color>; /* Modal shadow */
--auth-container-border-bottom-color: <color>;
--auth-container-background-color: <color>;
--auth-container-errors-color: <color>;
--btn-authorize-background-color: <color>;
--btn-authorize-border-color: <color>;
--btn-authorize-font-color: <color>;
--btn-authorize-svg-fill-color: <color>;

Operations Panel

--opblock-tag-section-border-color: <color>;
--opblock-tag-section-expandcollapse-background-color: <color>;
--opblock-tag-background-color-hover: <color>;
--opblock-tag-pinned-background-color-hover: <color>;
--opblock-tag-border-bottom-color: <color>;
--opblock-border-color: <color>;
--opblock-shadow-color: <color>;
--opblock-tabheader-underline-color: <color>;
--opblock-summary-svg-icons-color: <color>;
--opblock-summary-border-bottom-color: <color>;
--opblock-section-header-background-color: <color>;
--opblock-section-header-shadow-color: <color>;
--opblock-summary-method-background-color: <color>;
--opblock-summary-method-color: <color>;
--opblock-summary-method-shadow-color: <color>;

HTTP Methods

/* GET */
--opblock-get-background-color: <color>;
--opblock-get-method-color: <color>;
--opblock-get-border-color: <color>;

/* POST */
--opblock-post-background-color: <color>;
--opblock-post-method-color: <color>;
--opblock-post-border-color: <color>;

/* PUT */
--opblock-put-background-color: <color>;
--opblock-put-method-color: <color>;
--opblock-put-border-color: <color>;

/* DELETE */
--opblock-delete-background-color: <color>;
--opblock-delete-method-color: <color>;
--opblock-delete-border-color: <color>;

/* PATCH */
--opblock-patch-background-color: <color>;
--opblock-patch-method-color: <color>;
--opblock-patch-border-color: <color>;

/* HEAD */
--opblock-head-background-color: <color>;
--opblock-head-method-color: <color>;
--opblock-head-border-color: <color>;

/* OPTIONS */
--opblock-options-background-color: <color>;
--opblock-options-method-color: <color>;
--opblock-options-border-color: <color>;

/* Deprecated */
--opblock-deprecated-background-color: <color>;
--opblock-deprecated-method-color: <color>;
--opblock-deprecated-border-color: <color>;

Tabs & Responses

--swagger-tabs-divider-color: <color>;
--response-undocumented-color: <color>;
--response-control-media-type-color: <color>;
--opblock-pre-microlight-background-color: <color>;
--opblock-pre-microlight-color: <color>;

Code Blocks

--download-contents-background-color: <color>;
--download-contents-color: <color>;
--copy-to-clipboard-background-color: <color>;
--copy-to-clipboard-icon: url('<image/svg>') 50% no-repeat;

Filters & Tables

--filter-operation-filter-input-border-color: <color>;
--filter-download-failed-color: <color>;
--filter-download-loading-color: <color>;
--table-headers-example-color: <color>;
--table-thead-border-bottom-color: <color>;

Parameters

--parameter-name-required-symbol-color: <color>;
--parameter-name-required-color: <color>;
--parameter-in-extension-color: <color>;
--parameter-deprecated-color: <color>;

Buttons

--button-background-color: <color>;
--button-border-color: <color>;
--button-shadow-color: <color>;
--button-shadow-hover-color: <color>;

/* Cancel Button */
--button-cancel-background-color: <color>;
--button-cancel-border-color: <color>;
--button-cancel-color: <color>;

/* Execute Button */
--button-execute-background-color: <color>;
--button-execute-border-color: <color>;
--button-execute-color: <color>;

/* Invalid State */
--button-invalid-background-color: <color>;
--button-invalid-border-color: <color>;

Expand/Collapse Icons

--expand-operation-svg-arrow-color: <color>;
--expand-operation-svg-arrow-hover-color: <color>;

Form Elements

/* Select Dropdown */
--select-background-icon: <color> url('<image/svg>') right 10px center no-repeat;
--select-border-color: <color>;
--select-shadow-color: <color>;
--select-disabled-border-color: <color>;

/* Input Fields */
--input-background-color: <color>;
--input-border-color: <color>;
--input-disabled-background-color: <color>;
--input-disabled-color: <color>;

/* Invalid State */
--input-invalid-background-color: <color>;
--input-invalid-border-color: <color>;
--input-invalid-color: <color>;

/* Textarea */
--textarea-background-color: <color>;
--textarea-border-focus-color: <color>;
--textarea-disabled-background-color: <color>;
--textarea-disabled-color: <color>;
--textarea-curl-background-color: <color>;
--textarea-curl-color: <color>;

/* Checkbox */
--checkbox-color: <color>;
--checkbox-label-item-background-color: <color>;
--checkbox-label-item-shadow-color: <color>;
--checkbox-label-item-icon: <color> url('<image/svg>') 50% no-repeat;

Dialog/Modal

--dialog-backdrop-color: <color>;
--dialog-background-color: <color>;
--dialog-border-color: <color>;
--dialog-shadow-color: <color>;
--dialog-close-button-icon-color: <color>;

Models/Schemas

--model-deprecated-color: <color>;
--model-arrow-icon: url('<image/svg>') 50% no-repeat;
--model-hint-background-color: <color>;
--model-hint-color: <color>;
--model-property-color: <color>;
--model-property-primitive-color: <color>;
--model-property-required-symbol-color: <color>;
--model-property-description: <color>;
--model-property-extension: <color>;
--model-section-border-color: <color>;
--model-section-header-color: <color>;
--model-section-header-hover-background-color: <color>;
--model-section-little-header-color: <color>;
--model-container-background-color: <color>;
--model-container-hover-background-color: <color>;
--model-box-background-color: <color>;
--model-title-color: <color>;
--model-deprecated-warning-color: <color>;
--model-prop-type-color: <color>;
--model-prop-format-color: <color>;
--expand-model-svg-arrow-color: <color>;

Rendered Markdown

--rendered-markdown-pre-color: <color>;
--rendered-markdown-code-background-color: <color>;
--rendered-markdown-code-color: <color>;

Scrollbar

--scrollbar-thumb-color: <color>;
--scrollbar-thumb-hover-color: <color>;

Back to Top Button

--scroll-to-top-button-background-color: <color>;
--scroll-to-top-button-hover-background-color: <color>;
--scroll-to-top-button-border-color: <color>;
--scroll-to-top-button-icon-color: <color>;
--scroll-to-top-button-shadow-color: <color>;

Customization Example

Simple Color Override

:root {
  /* Change primary colors */
  --swagger-main-color: #e74c3c;
  --body-background-color: #2c3e50;
}

Complete Theme Customization

:root {
  /* Core */
  --body-background-color: #1a1a2e;
  --swagger-main-color: #00d9ff;

  /* Topbar */
  --topbar-background-color: #16213e;
  --topbar-pinned-background-color: rgba(22, 33, 62, 0.95);
  --topbar-pinned-shadow-color: rgba(0, 217, 255, 0.3);

  /* GET requests - blue */
  --opblock-get-background-color: rgba(0, 217, 255, 0.1);
  --opblock-get-border-color: #00d9ff;
  --opblock-get-method-color: #00d9ff;

  /* POST requests - green */
  --opblock-post-background-color: rgba(0, 255, 127, 0.1);
  --opblock-post-border-color: #00ff7f;
  --opblock-post-method-color: #00ff7f;

  /* DELETE requests - red */
  --opblock-delete-background-color: rgba(255, 71, 87, 0.1);
  --opblock-delete-border-color: #ff4757;
  --opblock-delete-method-color: #ff4757;

  /* Buttons */
  --button-execute-background-color: #00d9ff;
  --button-execute-border-color: #00b8d4;
  --button-execute-color: #1a1a2e;

  /* Back to top */
  --scroll-to-top-button-background-color: #00d9ff;
  --scroll-to-top-button-hover-background-color: #00b8d4;
  --scroll-to-top-button-icon-color: #1a1a2e;
}

Brand-Specific Theme

:root {
  /* Your company colors */
  --swagger-main-color: #003d82; /* Company blue */
  --body-background-color: #ffffff;
  --topbar-background-color: #003d82;

  /* Branded operations */
  --opblock-get-background-color: #e3f2fd;
  --opblock-get-border-color: #003d82;
  --opblock-post-background-color: #e8f5e9;
  --opblock-post-border-color: #2e7d32;

  /* Branded buttons */
  --button-execute-background-color: #003d82;
  --button-execute-border-color: #002855;
}

Tip

Check out the Predefined Themes CSS in the repository for a complete list of available CSS variables used in each theme. You can just copy one of them and change the values as needed.

Troubleshooting

Variables Not Applying

Ensure you're not using a standalone theme:

Standalone themes and inline styles don't inherit CSS variables. Use a regular custom theme instead.

Next Steps

🏠 Home

🚀 Getting Started

✨ Features

📖 Migration Guides

Clone this wiki locally