{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"customize-color-modes","__idx":0},"children":["Customize color modes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use CSS styling and configuration changes to customize the color modes in your project."," ","When users switch between color modes, the documentation's appearance dynamically changes to the corresponding color mode."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["at least a few Markdown pages in your project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a basic understanding of CSS and Typescript"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-color-mode-styles","__idx":2},"children":["Configure color mode styles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The styling rules in this section are added to your project's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," file."," ","Create that file if you don't have one already."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"override-css-variables","__idx":3},"children":["Override CSS variables"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A good approach to customizing color mode styling is to override the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/css-variables"},"children":["CSS variables"]}," used throughout your project."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add color mode customization to your project's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," file using CSS variables."," ","The following example shows a complete color mode configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","data-title":"@theme/styles.css","header":{"title":"@theme/styles.css","controls":{"copy":{}}},"source":"/* Default color variables (used as fallbacks) */\n:root {\n  --color-primary: #2563eb;\n  --color-primary-hover: #1d4ed8;\n  --link-text-color: #1668dc;\n  --sidebar-background-color: #f8fafc;\n  --sidebar-active-background-color: #e2e8f0;\n  --text-color: #1f2937;\n  --bg-overlay: #f2f2f2;\n}\n\n/* Light mode specific styling */\n:root.light {\n  --sidebar-background-color: #ffffff;\n  --sidebar-active-background-color: var(--color-purple-2);\n  --text-color: #374151;\n  --navbar-background-color: #ffffff;\n}\n\n/* Dark mode specific styling */\n:root.dark {\n  --color-primary: #60a5fa;\n  --color-primary-hover: #3b82f6;\n  --link-text-color: #60a5fa;\n  --sidebar-background-color: #1e293b;\n  --sidebar-active-background-color: #334155;\n  --text-color: #f1f5f9;\n  --bg-overlay: #374151;\n  --navbar-background-color: #0f172a;\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, the colors and backgrounds change when users switch between light and dark modes, creating a cohesive experience across both modes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"css-variable-composition","__idx":4},"children":["CSS variable composition"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Element-specific CSS variables are often built upon another set of ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/color-mode#css-variables-as-building-blocks"},"children":["core CSS variables"]},"."," ","Consider the level of granularity you need before adding CSS variable overrides."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's use the example from the section above to illustrate the point."," ","The example added the following styling rules:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":root"]}," selector set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--bg-overlay"]}," variable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":root.dark"]}," selector set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--sidebar-active-background-color"]}," variable."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--bg-overlay"]}," serves as a building block for more than 30 other CSS variables!"," ","So, while the example ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["did"]}," successfully change the sidebar's active item background, it no longer matches any other elements built with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--bg-overlay"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generally speaking, we recommend overriding the foundational CSS variables when possible to maintain a more cohesive design."," ","Then you can override an element-specific CSS variable only when needed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"annotate-markdown-elements","__idx":5},"children":["Annotate Markdown elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding annotations to your Markdown elements gives them selectors."," ","Annotations are a good solution for adding color-mode-specific styling to elements that are otherwise difficult to select."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use annotation to apply styling for different color modes:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Markdoc tag syntax to add an annotation in your Markdown, as in the following example:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"example-page"},"children":["Example page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some content"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{"class":"awesome-list-entry"},"children":["List item "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List item 2"]}]}],"rawContent":"# Example page\n\nSome content\n\n- List item {% class=\"awesome-list-entry\" %}\n- List item 2\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," file, use the selector you added to define light and dark mode styling for the element, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","header":{"controls":{"copy":{}}},"source":":root.light .awesome-list-entry {\n  color: blue;\n}\n\n:root.dark .awesome-list-entry {\n  color: red;\n}\n","lang":"css"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the example above, the first entry in the list changes between blue and red text color when the user changes the color mode."," ","Annotations can be used to add classes or ids."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-color-mode-logo","__idx":6},"children":["Set color mode logo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can configure your documentation to use a different logo for each color mode."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set the logo per color mode:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add two versions of a logo to an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["images"]}," folder in the root of your project."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a single, comma-separated string that contains the logo's filepath and color mode name it corresponds with."," ","It should follow this pattern: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<logo-path> <color-mode-name>, <logo-path> <color-mode-name>"]}," and contain an entry for each color mode."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In your project's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," file, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["srcSet"]}," property on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logo"]}," object to pass the list of logos, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"logo:\n  srcSet: \"./images/your-light-logo.svg light, ./images/your-dark-logo.svg dark\"\n  altText: Your amazing logo\n  link: \"https://example.com\"\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the example above, the logo in the documentation navbar changes when the user switches between color modes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-new-color-modes","__idx":7},"children":["Add new color modes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add custom color modes beyond the default light and dark modes."," ","This creates new options in the color mode switcher and requires component ejection."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"before-you-begin-1","__idx":8},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a Redocly project set up and running locally"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["understanding of React and CSS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["familiarity with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/eject-components"},"children":["component ejection"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"eject-colormodeicon-component","__idx":9},"children":["Eject ColorModeIcon component"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/eject-components/eject-components-using-cli"},"children":["Eject"]}," the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ColorModeIcon"]}," component to add custom icons:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npx @redocly/cli eject component 'ColorModeSwitcher/ColorModeIcon.tsx'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-new-color-mode-icon","__idx":10},"children":["Add new color mode icon"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add an icon for the new color mode by creating a switch case in the ejected file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"@theme/components/ColorModeSwitcher/ColorModeIcon.tsx","header":{"title":"@theme/components/ColorModeSwitcher/ColorModeIcon.tsx","controls":{"copy":{}}},"source":"function Icon({ mode, className }: ColorModeIconProps) {\n  switch (mode) {\n    case 'high-contrast':\n      return (\n        <svg className={className} version=\"1.1\" viewBox=\"0 0 128 128\" xmlns=\"http://www.w3.org/2000/svg\">\n          <path d=\"m62 108v12c0 1.1055 0.89453 2 2 2s2-0.89453 2-2v-12c0-1.1055-0.89453-2-2-2s-2 0.89453-2 2zm43.012-5.8164-8.4844-8.4844c-0.78125-0.78516-2.0469-0.78516-2.8281 0-0.78516 0.78125-0.78516 2.0469 0 2.8281l8.4844 8.4844c0.78125 0.78125 2.0469 0.78125 2.8281 0s0.78125-2.0469 0-2.8281zm-73.539-8.4844-8.4844 8.4844c-0.78125 0.78125-0.78125 2.0469 0 2.8281s2.0469 0.78125 2.8281 0l8.4844-8.4844c0.78516-0.78125 0.78516-2.0469 0-2.8281-0.78125-0.78516-2.0469-0.78516-2.8281 0zm32.527 8.3008c20.973 0 38-17.027 38-38s-17.027-38-38-38-38 17.027-38 38 17.027 38 38 38zm-2-71.945v67.887c-17.836-1.0391-32-15.852-32-33.945s14.164-32.902 32-33.945z\" fill-rule=\"evenodd\"/>\n        </svg>\n      );\n    case 'dark':\n      return <SunIcon data-testid=\"dark\" />;\n    case 'light':\n      return <MoonIcon data-testid=\"light\" />;\n    default:\n      return <SunIcon data-testid=\"default\" />;\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"className prop required"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["className"]}," prop through to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<svg>"]}," element for proper styling."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"define-custom-color-mode-styles","__idx":11},"children":["Define custom color mode styles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add styling rules for your new color mode in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]},"."," ","The class name must match the color mode name:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","data-title":"@theme/styles.css","header":{"title":"@theme/styles.css","controls":{"copy":{}}},"source":":root.high-contrast {\n  /* High contrast color scheme */\n  --color-primary: #000000;\n  --text-color: #000000;\n  --bg-color: #ffffff;\n  --navbar-bg-color: #ffffff;\n  --sidebar-background-color: #ffffff;\n  --border-color: #000000;\n  --link-text-color: #000000;\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-to-configuration","__idx":12},"children":["Add to configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the new color mode to your project configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"colorMode: \n  modes: \n    - 'high-contrast'\n    - 'light'\n    - 'dark'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The first mode in the list is the default."," ","See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/color-mode"},"children":["colorMode configuration"]}," for all available options."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"test-your-new-color-mode","__idx":13},"children":["Test your new color mode"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx @redocly/cli preview"]}," to start your local preview"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the color mode switcher to toggle between modes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the new icon appears and styles are applied correctly"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Refine the styles in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," as needed"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-the-usecolorswitcher-hook","__idx":14},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["useColorSwitcher"]}," hook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["useColorSwitcher"]}," React hook to access the current color mode and switch modes from your custom components."," ","This is useful for adapting component behavior or visuals based on the active color mode, or for adding custom color mode controls."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The hook reads the current document color mode and updates the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<html>"]}," element classes when switching modes."," ","The list of supported modes comes from configuration."," ","If no modes are configured, the default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["light"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dark"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"usage","__idx":15},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import { useColorSwitcher } from '@redocly/theme';\n\nexport function ThemeToggleButton() {\n  const { activeColorMode, switchColorMode, isSwitcherHidden } = useColorSwitcher();\n\n  if (isSwitcherHidden) return null;\n\n  const nextLabel = activeColorMode === 'dark' ? 'Switch to light mode' : 'Switch to dark mode';\n\n  return (\n    <button type=\"button\" onClick={() => switchColorMode()}>\n      {nextLabel}\n    </button>\n  );\n}\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-a-specific-mode","__idx":16},"children":["Set a specific mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also set an explicit mode if it exists in your configured modes."," ","If an invalid mode is passed, the call is ignored."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"const { switchColorMode } = useColorSwitcher();\nswitchColorMode('dark'); // sets dark mode if supported\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api","__idx":17},"children":["API"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["activeColorMode"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," — The current color mode (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["light"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dark"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["switchColorMode"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["(mode?: string) => void"]}," — Call with no argument to cycle through configured modes."," ","Call with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," to set a specific supported mode."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":18},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/customize-styles"},"children":["Customize styles"]}]}," - Learn to customize your documentation's appearance using CSS variables and custom stylesheets for precise brand control"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/css-variables"},"children":["CSS variables"]}]}," - Complete dictionary of CSS variables available for color mode customization and styling"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding"},"children":["Style your site"]}]}," - Explore all available branding and customization approaches from basic configuration to advanced component ejection"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/eject-components"},"children":["Eject components"]}]}," - Technical guide to ejecting and customizing components like ColorModeIcon for advanced color mode features"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/color-mode"},"children":["Color mode configuration"]}]}," - Configuration reference for setting up color modes, default modes, and mode-specific options"]}]}]},"frontmatter":{},"tagList":["admonition","markdoc-example"],"title":"Customize color modes","lastModified":"2026-10-01T23:00:57.000Z"}