mkdocs-material/docs/guides/changing-colors.md

---
template: overrides/main.html
---

# Changing colors

As any good Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through 
`mkdocs.yml`. Furthermore, colors can be adjusted with a few lines of CSS to
fit your brand identity by using [CSS variables][2].

  [1]: http://www.materialui.co/colors
  [2]: #customization

## Configuration

### Color scheme

[:octicons-file-code-24: Source][3] · :octicons-tools-24: Default: `default`

Material for MkDocs supports two _color schemes_: a light mode, which is just
called `default`, and a dark mode, which is called `slate`. The color scheme
can be set from `mkdocs.yml`:

``` yaml
theme:
  palette:
    scheme: default
```

:material-cursor-default-click-outline: click on a tile to change the color
scheme:

<style>
  .md-typeset button[data-md-color-scheme] {
    cursor: pointer;
    transition: opacity 250ms;
  }
  .md-typeset button[data-md-color-scheme]:hover {
    opacity: 0.75;
  }
  .md-typeset button[data-md-color-scheme] > code {
    display: block;
    color: var(--md-primary-bg-color);
    background-color: var(--md-primary-fg-color);
  }
</style>

<button data-md-color-scheme="default"><code>default</code></button>
<button data-md-color-scheme="slate"><code>slate</code></button>

<script>
  var buttons = document.querySelectorAll("button[data-md-color-scheme]")
  buttons.forEach(function(button) {
    var attr = "data-md-color-scheme"
    button.addEventListener("click", function() {
      var name = document.querySelector("#__code_0 code span:nth-child(7)")
      document.body.setAttribute(attr, this.getAttribute(attr))
      name.textContent = this.getAttribute(attr)
    })
  })
</script>

The _color scheme_ can also be set based on _user preference_, which makes use
of the `prefers-color-scheme` media query. This can be done by adding the
following to `mkdocs.yml`:

``` yaml
theme:
  palette:
    scheme: preference
```

  [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss

### Primary color

[:octicons-file-code-24: Source][4] · :octicons-tools-24: Default: `indigo`

The _primary color_ is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
in `mkdocs.yml` to a valid color name:

``` yaml
theme:
  palette:
    primary: indigo
```

:material-cursor-default-click-outline: click on a tile to change the primary
color:

<style>
  .md-typeset button[data-md-color-primary] {
    cursor: pointer;
    transition: opacity 250ms;
  }
  .md-typeset button[data-md-color-primary]:hover {
    opacity: 0.75;
  }
  .md-typeset button[data-md-color-primary] > code {
    display: block;
    color: var(--md-primary-bg-color);
    background-color: var(--md-primary-fg-color);
  }
</style>

<button data-md-color-primary="red"><code>red</code></button>
<button data-md-color-primary="pink"><code>pink</code></button>
<button data-md-color-primary="purple"><code>purple</code></button>
<button data-md-color-primary="deep-purple"><code>deep purple</code></button>
<button data-md-color-primary="indigo"><code>indigo</code></button>
<button data-md-color-primary="blue"><code>blue</code></button>
<button data-md-color-primary="light-blue"><code>light blue</code></button>
<button data-md-color-primary="cyan"><code>cyan</code></button>
<button data-md-color-primary="teal"><code>teal</code></button>
<button data-md-color-primary="green"><code>green</code></button>
<button data-md-color-primary="light-green"><code>light green</code></button>
<button data-md-color-primary="lime"><code>lime</code></button>
<button data-md-color-primary="yellow"><code>yellow</code></button>
<button data-md-color-primary="amber"><code>amber</code></button>
<button data-md-color-primary="orange"><code>orange</code></button>
<button data-md-color-primary="deep-orange"><code>deep orange</code></button>
<button data-md-color-primary="brown"><code>brown</code></button>
<button data-md-color-primary="grey"><code>grey</code></button>
<button data-md-color-primary="blue-grey"><code>blue grey</code></button>
<button data-md-color-primary="black"><code>black</code></button>
<button data-md-color-primary="white"><code>white</code></button>

<script>
  var buttons = document.querySelectorAll("button[data-md-color-primary]")
  buttons.forEach(function(button) {
    var attr = "data-md-color-primary"
    button.addEventListener("click", function() {
      var name = document.querySelector("#__code_2 code span:nth-child(7)")
      document.body.setAttribute(attr, this.getAttribute(attr))
      name.textContent = this.getAttribute(attr)
    })
  })
</script>

  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss

### Accent color

[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: `indigo`

The _accent color_ is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
chosing a valid color name:

``` yaml
theme:
  palette:
    accent: indigo
```

:material-cursor-default-click-outline: click on a tile to change the accent
color:

<style>
  .md-typeset button[data-md-color-accent] {
    cursor: pointer;
    transition: opacity 250ms;
  }
  .md-typeset button[data-md-color-accent]:hover {
    opacity: 0.75;
  }
  .md-typeset button[data-md-color-accent] > code {
    display: block;
    color: var(--md-accent-fg-color);
  }
</style>

<button data-md-color-accent="red"><code>red</code></button>
<button data-md-color-accent="pink"><code>pink</code></button>
<button data-md-color-accent="purple"><code>purple</code></button>
<button data-md-color-accent="deep-purple"><code>deep purple</code></button>
<button data-md-color-accent="indigo"><code>indigo</code></button>
<button data-md-color-accent="blue"><code>blue</code></button>
<button data-md-color-accent="light-blue"><code>light blue</code></button>
<button data-md-color-accent="cyan"><code>cyan</code></button>
<button data-md-color-accent="teal"><code>teal</code></button>
<button data-md-color-accent="green"><code>green</code></button>
<button data-md-color-accent="light-green"><code>light green</code></button>
<button data-md-color-accent="lime"><code>lime</code></button>
<button data-md-color-accent="yellow"><code>yellow</code></button>
<button data-md-color-accent="amber"><code>amber</code></button>
<button data-md-color-accent="orange"><code>orange</code></button>
<button data-md-color-accent="deep-orange"><code>deep orange</code></button>

<script>
  var buttons = document.querySelectorAll("button[data-md-color-accent]")
  buttons.forEach(function(button) {
    var attr = "data-md-color-accent"
    button.addEventListener("click", function() {
      var name = document.querySelector("#__code_3 code span:nth-child(7)")
      document.body.setAttribute(attr, this.getAttribute(attr))
      name.textContent = this.getAttribute(attr)
    })
  })
</script>

  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss

## Customization

Material for MkDocs implements colors using [CSS variables][6] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional stylesheet][7] and
tweak the following CSS variables:

``` css
:root {

  /* Default color shades */
  --md-default-fg-color:               hsla(0, 0%, 0%, 0.87);
  --md-default-fg-color--light:        hsla(0, 0%, 0%, 0.54);
  --md-default-fg-color--lighter:      hsla(0, 0%, 0%, 0.32);
  --md-default-fg-color--lightest:     hsla(0, 0%, 0%, 0.07);
  --md-default-bg-color:               hsla(0, 0%, 100%, 1);
  --md-default-bg-color--light:        hsla(0, 0%, 100%, 0.7);
  --md-default-bg-color--lighter:      hsla(0, 0%, 100%, 0.3);
  --md-default-bg-color--lightest:     hsla(0, 0%, 100%, 0.12);

  /* Primary color shades */
  --md-primary-fg-color:               hsla(231, 48%, 48%, 1);
  --md-primary-fg-color--light:        hsla(231, 44%, 56%, 1);
  --md-primary-fg-color--dark:         hsla(232, 54%, 41%, 1);
  --md-primary-bg-color:               hsla(0, 0%, 100%, 1);
  --md-primary-bg-color--light:        hsla(0, 0%, 100%, 0.7);

  /* Accent color shades */
  --md-accent-fg-color:                hsla(231, 99%, 66%, 1);
  --md-accent-fg-color--transparent:   hsla(231, 99%, 66%, 0.1);
  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);
}
```

The colors of [code blocks][8], [admonitions][9], text links and the footer can
be adjusted through dedicated CSS variables, which partly default to the base
colors or neutral colors:

``` css
:root > * {

  /* Code color shades */
  --md-code-bg-color:                  hsla(0, 0%, 96%, 1);
  --md-code-fg-color:                  hsla(200, 18%, 26%, 1);

  /* Text color shades */
  --md-text-color:                     var(--md-default-fg-color);
  --md-text-link-color:                var(--md-primary-fg-color);

  /* Admonition color shades */
  --md-admonition-bg-color:            var(--md-default-bg-color);
  --md-admonition-fg-color:            var(--md-default-fg-color);

  /* Footer color shades */
  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.3);
}
```

  [6]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
  [7]: ../getting-started/customization.md#additional-stylesheets
  [8]: ../extensions/codehilite.md
  [9]: ../extensions/admonition.md

## Caveats

!!! warning "Accessibility – not all color combinations work well"

    With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
    = __714__ combinations, it's impossible to ensure that all configurations
    provide a good user experience (e.g. _yellow on light background_), so make
    sure that the color combination of your choosing provides enough contrast
    and tweak CSS variables where necessary.