Improve Dark Mode support and add configuration options for default theme #10663
Description
Dark mode was introduced in PR #10653 and is currently available via the Standalone layout toggle or by manually adding the dark-mode class to the <html> element.
However, the current implementation has a few limitations that make it hard to use in real-world and embedded scenarios.
Current limitations
- There is no configuration option to enable dark mode by default via Swagger UI configuration.
- The dark mode toggle is only available in
StandaloneLayoutPreset, which limits usability in custom or embedded builds. - Enabling dark mode by adding a
dark-modeclass to<html>can interfere with host application styles. - There is no official documentation or examples for enabling dark mode in:
- embedded / iframe usage
swagger-ui-react- custom NPM or Docker deployments
Proposed improvements
- Add a configuration flag (e.g.
defaultDarkMode: true) to enable dark mode without DOM manipulation. - Scope dark mode styles to Swagger UI containers to prevent CSS bleed into host applications.
- Expose dark mode support consistently across all layouts, not only the standalone one.
- Add documentation and examples covering common integration patterns.
- (Optional) Allow basic theme customization (custom colors, high-contrast mode, etc.).
Example configuration (proposal)
SwaggerUI({
dom_id: '#swagger-ui',
url: '/openapi.json',
presets: [SwaggerUIBundle.presets.apis],
theme: {
defaultMode: 'dark'
}
});