PatternFly dark theme handbook

Enabling dark theme

Dark theme styles ship with PatternFly CSS by default. To enable dark theme, add the class pf-[version]-theme-dark (for example, pf-v6-theme-dark) to your application's <html> tag. This class can be added dynamically to toggle dark theme on and off in your application.

Dark theme can also be applied based on the browser’s prefers-color-scheme media query. When using this method, we recommend using JavaScript to detect the media query and apply the pf-[version]-theme-dark class. This allows you to manipulate a single class in order to toggle dark theme based on user preference. Adam Argyle wrote a great article on using JavaScript to manage dark theme preference, using the prefers-color-scheme media query alongside a manual button that toggles dark theme.

Our token resources include styles for both light and dark themes. When dark theme is enabled, your product will automatically pull dark theme tokens in order to adapt visual styles appropriately.

Best practices

To make it easier to support light and dark theming in your application, we recommend following these best practices during design and development:

  • Use PatternFly components without customizations. Most problems with dark theming are due to the use of custom styles, overrides to PatternFly styles, and non-PatternFly components. To ensure consistent styling and behavior when switching themes, try to use PatternFly components as they are.

  • Use tokens and component variables to define any overrides.

    • For example, to override a primary button’s background color, declare .pf-[version]-c-button { --pf-[version]-c-button--m-primary--BackgroundColor: [color token]; } instead of .pf-[version] { background-color: [color token]; }.
  • Use tokens in custom styles.

    • For example, use background-color: var(--pf-t--[version]--global--background--color--primary--default) for a primary background instead of background-color: #fff or background-color: white. Values like #fff and white will not change between light and dark theme, but tokens will.
  • Always use the most relevant semantic token for your use case. If there isn't a semantic token for your scenario, then you can use a base token. Never use a palette token directly in your code.

    • For example, --pf-t--[version]--global--text--color--link--default, --pf-t--[version]--color--blue--20, and #b9dafc are all the same in PatternFly's default light theme. When you create something custom, where the color should match the application’s link text color, any of these values will work. However, in a different theme, these token values may not always be the same color.
  • Use SVG files or icon fonts for icons, and use tokens for icon colors. To easily manipulate icon colors between light and dark theme, SVG files and icon fonts can be changed via CSS by using the fill and color properties. When using semantic tokens, like --pf-t--[version]--global--color--status--info--default, colors will automatically adjust between light and dark theme. If images must be used, we advise you to use colors that work well in both light and dark themes and/or hide and show the appropriate images based on the presence of the dark theme body class.

View source on GitHub