Skip to main content

CSS Variables

Docusaurus Documentation: Styling your site with Infima

Work in Progress

This documentation is a work in progress. If you have any questions or suggestions, please feel free to open an issue on the Docusaurus Community Website GitHub repository.

The process of documenting these variables is fairly slow and time-consuming, so please be patient.

Docusaurus uses CSS variables to define the colors, fonts, and spacing used in the design system. This allows you to easily customise the look and feel of your site by changing a few variables.

Docusaurus CSS variables typically come from two sources each with a naming convention:

  • Infima Variables: These are the core variables used by the Infima CSS framework. They are prefixed with --ifm-. Typically these variables are used for colors, core layout, and typography.
  • Docusaurus Variables: These are variables specific to Docusaurus. They are prefixed with --docusaurus-. Typically these variables are used for Docusaurus specific components and features not covered by Infima's more generic approach.

Some plugins bring their own CSS variables, the Algolia search plugin for example uses --docsearch prefixed variables.

What are CSS Variables?​

CSS variables are a way to define reusable values in CSS. They are defined using the -- prefix and can be used in any CSS property. For example, you can define a color variable like this:

:root {
  --my-color: red;
}

And then use it in your CSS like this:

h1 {
  color: var(--my-color);
}

More information on CSS variables can be found in the MDN Web Docs and W3 Schools.

Are All CSS Variables Documented?​

No, not all CSS variables Docusaurus uses are documented. The most common variables are documented here, but there are many more variables used in the Docusaurus codebase. If you need to customize a variable that is not documented here, you can inspect the CSS of your site to find the variable name.

This documentation aims to document the most commonly used variables to help you get started with customising your site.

Where Should I Set CSS Variables?​

CSS variables can be set in a few different places:

  • Global CSS: You can set CSS variables in your global CSS file (e.g., src/css/custom.css or src/scss/custom.scss if you're using SASS).
  • Component Styles: You can set CSS variables in the styles of individual components. In the respective component's CSS Module file.

One thing that's important to note is that it is not always appropriate to set variables in :root or html[data-theme=dark]. Docusaurus sets the value of several variables outside of :root to allow for more granular control. For this reason you may find that setting a variable in :root does not have the desired effect and you need to scope it more specifically.

Here's an example from the Docusaurus codebase, we can see from the list below that the footer uses various --ifm-footer-* variables. If you wanted to change the background color of the footer, you would set the --ifm-footer-background-color variable in your CSS like this, at least that's the theory:

:root {
  --ifm-footer-background-color: #303846;
}

Seems clear enough. However that bit of CSS will not work as expected. The footer is styled using the .footer or .footer-dark classes, so you need to set the variable like this:

.footer {
  --ifm-footer-background-color: #303846;
}

or like this:

.footer-dark {
  --ifm-footer-background-color: #303846;
}

Inspecting the styles in your browser's dev tools can help you identify the correct class to target if your variable overrides are not working as expected.

Key Infima Variables​

Colors​

There are a number of variables for the "base" colors used on your site. These are the most common colors used in the design system. A vague attempt has been made to group these (using blank rows) according broadly to their use.

VariableDescriptionDefault (Light)Default (Dark)
--ifm-color-primaryThe primary color used by the site.

#2e8555

#25c2a0
--ifm-color-secondaryThe secondary color used by the site.

#ebedf0

#ebedf0
--ifm-color-successThe success color used by the site.

#00a400

#00a400
--ifm-color-infoThe info color used by the site.

#54c7ec

#54c7ec
--ifm-color-warningThe warning color used by the site.

#ffba00

#ffba00
--ifm-color-dangerThe danger color used by the site.

#fa3e3e

#fa3e3e
--ifm-color-whiteThe white color used by the site.

#fff

#fff
--ifm-color-blackThe black color used by the site.

#000

#000
--ifm-color-contentThe color used for content elements on the site.

#1c1e21

#e3e3d3
--ifm-color-content-inverseThe inverse color used for content elements on the site.

var(--ifm-color-emphasis-0)

var(--ifm-color-emphasis-0)
--ifm-color-content-secondaryA secondary color used for content elements on the site.

#525860

rgba(255, 255, 255, 1)
--ifm-background-colorThe background color used by the site.

#fff

#1b1b1d
--ifm-font-color-baseThe base font color used by the site.

var(--ifm-color-content)

var(--ifm-color-content)
--ifm-font-color-base-inverseThe inverse base font color used by the site.

var(--ifm-color-content-inverse)

var(--ifm-color-content-inverse)
--ifm-font-color-secondaryThe secondary font color used by the site.

var(--ifm-color-content-secondary)

var(--ifm-color-content-secondary)
--ifm-background-surface-colorThe surface background color used by the site.

var(--ifm-color-content-inverse)

#242526
--ifm-hover-overlayThe overlay color used when hovering over elements.

rgba(0, 0, 0, 0.05)

rgba(255, 255, 255, 0.05)
--ifm-link-colorThe color of links on the site.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-link-hover-colorThe color of links on the site when hovered.

var(--ifm-link-color)

var(--ifm-link-color)
--ifm-blockquote-colorThe color of blockquotes on the site.

var(--ifm-color-emphasis-800)

var(--ifm-color-emphasis-800)
--ifm-blockquote-border-colorThe border color of blockquotes on the site.

var(--ifm-color-emphasis-300)

var(--ifm-color-emphasis-300)
--ifm-hr-background-colorThe background color of horizontal rules on the site.

var(--ifm-color-gray-500)

var(--ifm-color-gray-500)
--ifm-color-gray-0The lightest gray color used by the site.

#fff

#fff
--ifm-color-gray-100A light gray color used by the site.

#f5f6f7

#f5f6f7
--ifm-color-gray-200A light gray color used by the site.

#ebedf0

#ebedf0
--ifm-color-gray-300A light gray color used by the site.

#dadde1

#dadde1
--ifm-color-gray-400A medium gray color used by the site.

#ccd0d5

#ccd0d5
--ifm-color-gray-500A medium gray color used by the site.

#bec3c9

#bec3c9
--ifm-color-gray-600A medium gray color used by the site.

#8d949e

#8d949e
--ifm-color-gray-700A dark gray color used by the site.

#606770

#606770
--ifm-color-gray-800A dark gray color used by the site.

#444950

#444950
--ifm-color-gray-900A dark gray color used by the site.

#1c1e21

#1c1e21
--ifm-color-gray-1000The darkest gray color used by the site.

#000

#000
--ifm-color-emphasis-0The color used for emphasis elements on the site.

var(--ifm-color-gray-0)

var(--ifm-color-gray-1000)
--ifm-color-emphasis-100The color used for emphasis elements on the site.

var(--ifm-color-gray-100)

var(--ifm-color-gray-900)
--ifm-color-emphasis-200The color used for emphasis elements on the site.

var(--ifm-color-gray-200)

var(--ifm-color-gray-800)
--ifm-color-emphasis-300The color used for emphasis elements on the site.

var(--ifm-color-gray-300)

var(--ifm-color-gray-700)
--ifm-color-emphasis-400The color used for emphasis elements on the site.

var(--ifm-color-gray-400)

var(--ifm-color-gray-600)
--ifm-color-emphasis-500The color used for emphasis elements on the site.

var(--ifm-color-gray-500)

var(--ifm-color-gray-500)
--ifm-color-emphasis-600The color used for emphasis elements on the site.

var(--ifm-color-gray-600)

var(--ifm-color-gray-400)
--ifm-color-emphasis-700The color used for emphasis elements on the site.

var(--ifm-color-gray-700)

var(--ifm-color-gray-300)
--ifm-color-emphasis-800The color used for emphasis elements on the site.

var(--ifm-color-gray-800)

var(--ifm-color-gray-200)
--ifm-color-emphasis-900The color used for emphasis elements on the site.

var(--ifm-color-gray-900)

var(--ifm-color-gray-100)
--ifm-color-emphasis-1000The color used for emphasis elements on the site.

var(--ifm-color-gray-1000)

var(--ifm-color-gray-0)
--ifm-alert-background-colorThe background color used for alerts. Overridden by specific alert styling.

inherit

inherit
--ifm-alert-border-colorThe border color used for alerts. Overridden by specific alert styling.`

inherit

inherit
`
--ifm-alert-colorThe text color used for alerts. Overridden by specific alert styling.

var(--ifm-font-color-base)

var(--ifm-font-color-base)
--ifm-badge-background-colorThe background color used for badges. Overridden by specific badge styling.

inherit

inherit
--ifm-badge-border-colorThe border color used for badges. Overridden by specific badge styling.

inherit

inherit
--ifm-badge-colorThe text color used for badges. Overridden by specific badge styling.

var(--ifm-color-white

var(--ifm-color-white)
--ifm-breadcrumb-color-activeThe color of the active breadcrumb item.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-breadcrumb-item-background-activeThe background color of the active breadcrumb item.

var(--ifm-hover-overlay)

var(--ifm-hover-overlay)
--ifm-button-background-colorThe background color used for buttons. Overridden by specific button styling.

inherit

inherit
--ifm-button-border-colorThe border color used for buttons.

var(--ifm-button-background-color)

var(--ifm-button-background-color)
--ifm-button-colorThe text color used for buttons. Overridden by specific button styling.

var(--ifm-font-color-base-inverse)

var(--ifm-font-color-base-inverse)
--ifm-card-background-colorThe background color of cards.

var(--ifm-background-surface-color)

var(--ifm-background-surface-color)
--ifm-dropdown-link-colorThe color of links in dropdowns.

var(--ifm-font-color-base)

var(--ifm-font-color-base)
--ifm-dropdown-hover-background-colorThe background color of dropdown items when hovered.

var(--ifm-hover-overlay)

var(--ifm-hover-overlay)
--ifm-footer-background-colorThe background color of the footer.

#303846

#303846
--ifm-footer-colorThe color of text in the footer.

inherit

inherit
--ifm-footer-link-colorThe color of links in the footer.

var(--ifm-color-secondary)

var(--ifm-color-secondary)
--ifm-footer-link-hover-colorThe color of links in the footer when hovered.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-footer-title-colorThe color of titles in the footer.

var(--ifm-color-white)

var(--ifm-color-white)
--ifm-hero-background-colorThe background color of the hero.

var(--ifm-background-surface-color)

var(--ifm-background-surface-color)
--ifm-hero-text-colorThe color of text in the hero.

var(--ifm-color-emphasis-800)

var(--ifm-color-emphasis-800)
--ifm-menu-colorThe color of text in the menu.

var(--ifm-color-emphasis-700)

var(--ifm-color-emphasis-700)
--ifm-menu-color-activeThe color of the active menu item.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-menu-color-background-activeThe background color of the active menu item.

var(--ifm-hover-overlay)

var(--ifm-hover-overlay)
--ifm-menu-color-background-hoverThe background color of menu items when hovered.

var(--ifm-hover-overlay)

var(--ifm-hover-overlay)
--ifm-navbar-background-colorThe background color of the navbar.

var(--ifm-background-surface-color)

var(--ifm-background-surface-color)
--ifm-navbar-link-colorThe color of links in the navbar.

var(--ifm-font-color-base)

var(--ifm-font-color-base)
--ifm-navbar-link-hover-colorThe color of links in the navbar when hovered.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-navbar-link-active-colorThe color of the active link in the navbar.

var(--ifm-link-color)

var(--ifm-link-color)
--ifm-navbar-search-input-background-colorThe background color of the search input in the navbar.

var(--ifm-color-emphasis-200)

var(--ifm-color-emphasis-200)
--ifm-navbar-search-input-colorThe color of the search input text in the navbar.

var(--ifm-color-emphasis-800)

var(--ifm-color-emphasis-800)
--ifm-navbar-search-input-placeholder-colorThe color of the search input placeholder text in the navbar.

var(--ifm-color-emphasis-500)

var(--ifm-color-emphasis-500)
--ifm-pagination-color-activeThe color of the active page in the pagination component.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-pills-color-activeThe color of the active pill in the pills component.

var(--ifm-color-primary)

var(--ifm-color-primary)
`--ifm-pills-color-background-activeThe background color of the active pill in the pills component.

var(--ifm-hover-overlay)

var(--ifm-hover-overlay)
--ifm-toc-border-colorThe color of the border around the table of contents.

var(--ifm-color-emphasis-300)

var(--ifm-color-emphasis-300)
--ifm-toc-link-colorThe color of links in the table of contents.

var(--ifm-color-content-secondary)

var(--ifm-color-content-secondary)
--ifm-tabs-colorThe color of the tab labels.

var(--ifm-color-secondary)

var(--ifm-color-secondary)
--ifm-tabs-color-activeThe color of the active tab label.

var(--ifm-color-primary)

var(--ifm-color-primary)
--ifm-tabs-color-active-borderThe color of the active tab label border.

var(--ifm-tabs-color-active)

var(--ifm-tabs-color-active)
--ifm-code-backgroundThe background color of code blocks.Determined by Prism ThemeDetermined by Prism Theme
--ifm-pre-backgroundThe background color of <pre> elements.Determined by Prism ThemeDetermined by Prism Theme
--ifm-pre-colorThe color of text in <pre> elements.Determined by Prism ThemeDetermined by Prism Theme
--ifm-heading-colorThe color of headings.

inherit

inherit
--ifm-table-backgroundThe background color of tables.

transparent

transparent
--ifm-table-stripe-backgroundThe background color of striped rows in tables.

rgba(0,0,0, 0.03)

#ffffff12
Color Variants

The Infima CSS framework has a mostly consistent naming convention for color variables. The color variables are named using the following pattern: --ifm-color-{color}. For example, the primary color variable is --ifm-color-primary. Most color variables have some other variants as follows:

VariantDescription
--ifm-color-{color}-lightA lighter shade of the color. Uses the tint() function to make the color 15% lighter.
--ifm-color-{color}-ligherAn even lighter shade of the color. Uses the tint() function to make the color 30% lighter.
--ifm-color-{color}-lightestThe lightest shade of the color. Uses the tint() function to make the color 50% lighter.
--ifm-color-{color}-darkA darker shade of the color. Uses the shade() function to make the color 10% darker.
--ifm-color-{color}-darkerAn even darker shade of the color. Uses the shade() function to make the color 15% darker.
--ifm-color-{color}-darkestThe darkest shade of the color. Uses the shade() function to make the color 30% darker.
--ifm-color-{color}-contrast-foregroundA color that contrasts well with the color for foreground elements. Uses the shade function to make the color 70% darker, 90% in dark mode.
--ifm-color-{color}-contrast-backgroundA color that contrasts well with the color for background elements. Uses the tint function to make the color 90% lighter, 70% in dark mode.

Typography​

Many of the infima variables are related to typography. These variables are used to define the font family, size, and weight used in the design system.

VariableDescriptionDefaultResult
--ifm-font-family-baseThe base font family used by the site.system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"
--ifm-font-family-monospaceThe monospace font family used by the site.SFMono-Regular, Menlo, Monaco, Consolas "Liberation Mono", "Courier New", monospace
--ifm-font-size-baseThe base font size used by the site.100%
--ifm-font-weight-baseThe base font weight used by the site.var(--ifm-font-weight-normal)400
--ifm-font-weight-lightA lighter font weight used by the site.300
--ifm-font-weight-normalThe normal font weight used by the site.400
--ifm-font-weight-semiboldA semi-bold font weight used by the site.500
--ifm-font-weight-boldThe bold font weight used by the site.700
--ifm-line-height-baseThe base line height used by the site.1.65
--ifm-heading-font-familyThe font family used for headings.var(--ifm-font-family-base)system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"
--ifm-heading-h1-font-sizeThe font size used for h1 elements.2rem
--ifm-heading-h2-font-sizeThe font size used for h2 elements.1.5rem
--ifm-heading-h3-font-sizeThe font size used for h3 elements.1.25rem
--ifm-heading-h4-font-sizeThe font size used for h4 elements.1rem
--ifm-heading-h5-font-sizeThe font size used for h5 elements.0.875rem
--ifm-heading-h6-font-sizeThe font size used for h6 elements.0.85rem
--ifm-heading-font-weightThe font weight used for headings.var(--ifm-font-weight-bold)700
--ifm-heading-line-heightThe line height used for headings.1.25
--ifm-link-decorationThe text decoration used for links.none
--ifm-link-hover-decorationThe text decoration used for links when hovered.underline
--ifm-leading-desktopThe line height used for paragraphs on desktop.1.25
--ifm-leadingThe line height used for paragraphs.calc(var(--ifm-leading-desktop) * 1rem);1.25rem
--ifm-paragraph-margin-bottomThe margin bottom used for paragraphs.var(--ifm-leading)1.25rem
--ifm-blockquote-font-sizeThe font size used for blockquotes.var(--ifm-font-size-base)100%
--ifm-code-font-sizeThe font size used for code blocks.90%
--ifm-button-font-weightThe font weight used for buttons.var(--ifm-font-weight-bold)700
--ifm-dropdown-font-weightThe font weight used for dropdowns.var(--ifm-font-weight-semibold)500
--ifm-pagination-font-sizeThe font size used for pagination.1rem

Spacing​

The infima variables are used to define the spacing used in the design system. These variables are used to define the padding and margin of various elements.

VariableDescriptionDefaultResult
--ifm-global-spacingThe global spacing used by the site.1rem
--ifm-spacing-verticalThe vertical spacing used by the site.var(--ifm-global-spacing)1rem
--ifm-spacing-horizontalThe horizontal spacing used by the site.var(--ifm-global-spacing)1rem
--ifm-alert-padding-verticalThe vertical padding used for alerts.var(--ifm-spacing-vertical)1rem
--ifm-alert-padding-horizontalThe horizontal padding used for alerts.var(--ifm-spacing-horizontal)1rem
--ifm-avatar-intro-marginThe margin used for the intro of avatars.1rem
--ifm-badge-padding-verticalThe vertical padding used for badges.calc(var(--ifm-spacing-vertical) * 0.25)0.25rem
--ifm-badge-padding-horizontalThe horizontal padding used for badges.calc(var(--ifm-spacing-horizontal) * 0.5)0.5rem
--ifm-breadcrumb-padding-verticalThe vertical padding used for breadcrumbs.0.4rem
--ifm-breadcrumb-padding-horizontalThe horizontal padding used for breadcrumbs.0.8rem
--ifm-breadcrumb-separator-sizeThe size of the breadcrumb separator.0.5rem
--ifm-breadcrumb-separator-size-multiplierThe multiplier used for the breadcrumb separator.1.25
--ifm-button-group-spacingThe spacing used for button groups.2px
--ifm-button-padding-verticalThe vertical padding used for buttons.0.375rem
--ifm-button-padding-horizontalThe horizontal padding used for buttons.1.5rem
--ifm-button-size-multiplierThe multiplier used for button sizes.1
--ifm-card-vertical-spacingThe vertical spacing used for cards.var(--ifm-global-spacing)1rem
--ifm-card-horizontal-spacingThe horizontal spacing used for cards.var(--ifm-global-spacing)1rem
--ifm-footer-link-horizontal-spacingThe horizontal spacing used for footer links.0.5rem
--ifm-footer-padding-verticalThe vertical padding used for footers.calc(var(--ifm-spacing-vertical) * 2)2rem
--ifm-fotter-padding-horizontalThe horizontal padding used for footers.calc(var(--ifm-spacing-horizontal) * 2)2rem
--ifm-menu-link-padding-verticalThe vertical padding used for menu links.0.375rem
--ifm-menu-link-padding-horizontalThe horizontal padding used for menu links.0.75rem
--ifm-navbar-item-padding-verticalThe vertical padding used for navbar items.0.25rem
--ifm-navbar-item-padding-horizontalThe horizontal padding used for navbar items.0.75rem
--ifm-navbar-padding-verticalThe vertical padding used for navbars.calc(var(--ifm-spacing-vertical) * 0.5)0.5rem
--ifm-navbar-padding-horizontalThe horizontal padding used for navbars.var(--ifm-spacing-horizontal)1rem
--ifm-pagination-page-spacingThe column gap / spacing used for pagination.0.2em
--ifm-pagination-padding-verticalThe vertical padding used for pagination.calc(var(--ifm-spacing-vertical) * 0.25)0.25rem
--ifm-pagination-padding-horizontalThe horizontal padding used for pagination.calc(var(--ifm-spacing-horizontal) * 1)1rem
--ifm-pills-spacingThe spacing used for pills.0.125rem
--ifm-toc-padding-verticalThe vertical padding used for the table of contents.0.5rem
--ifm-toc-padding-horizontalThe horizontal padding used for the table of contents.0.5rem
--ifm-tabs-padding-verticalThe vertical padding used for tabs.1rem
--ifm-tabs-padding-horizontalThe horizontal padding used for tabs.1rem
--ifm-code-padding-verticalThe vertical padding used for code blocks.0.1rem
--ifm-code-padding-horizontalThe horizontal padding used for code blocks.0.1rem
--ifm-pre-paddingThe padding used for <pre> elements.1rem
--ifm-heading-margin-bottomThe margin bottom used for headings.var(--ifm-spacing-vertical)1rem
--ifm-heading-margin-topThe margin top used for headings.0
--ifm-image-alignment-paddingThe padding used for image alignments.1.25rem
--ifm-list-left-paddingThe left padding used for lists.2rem
--ifm-list-marginThe margin used for lists.1rem
--ifm-list-item-marginThe margin used for list items.0.25rem
--ifm-list-paragraph-marginThe margin used for list paragraphs.1rem
--ifm-table-cell-paddingThe padding used for table cells.0.75rem