Quarto Themes: Bootswatch List, Dark Mode and SCSS

November 11, 2026 · 10 min read

Quarto Themes: Bootswatch List, Dark Mode and Custom SCSS

Quarto themes control how HTML documents, websites and dashboards look. You set them with the theme option and pick one of 25 Bootswatch themes or Bootstrap's default. Pair a light theme with a dark one for a reader toggle, then adjust colors and fonts in an SCSS file.

If you're new to .qmd files themselves, our Quarto Markdown guide covers the document format. This post sticks to styling the output.

What Themes Are Available in Quarto?

Quarto renders HTML with Bootstrap 5 and bundles 25 themes from the Bootswatch project. Add Bootstrap's own default and you get 26 valid names for the theme option, all listed on the HTML Theming page of the Quarto docs.

LookTheme names
Light backgroundsdefault, cerulean, cosmo, flatly, journal, litera, lumen, lux, materia, minty, morph, pulse, sandstone, simplex, sketchy, spacelab, united, yeti, zephyr
Dark backgroundscyborg, darkly, quartz, slate, solar, superhero, vapor

The split comes from each theme's background variable in the Bootswatch source. Quartz is the odd one out: it uses a cyan, purple and pink gradient background with white text, so treat it as dark when you pair themes.

R Markdown's html_document uses an older Bootswatch list with names like paper and readable that Quarto doesn't ship. Our R Markdown YAML header guide has that list if you're migrating.

To compare them, render one test page with a few candidate names, or browse the previews on the Bootswatch site. To see which variables a theme sets, open Quarto's merged copy of each Bootswatch file in the quarto-cli repository on GitHub.

We prefer starting from cosmo or flatly and changing a few variables over hunting through all 26 for a perfect preset. Both are neutral, readable and easy to recolor.

Setting a Quarto Theme in a Document, Website or Dashboard

For a single document, put the theme under format in the YAML header:

format:
  html:
    theme: cosmo

That renders the page with the Cosmo palette, fonts and spacing. For a website, put the same block in _quarto.yml so every page picks it up. Dashboards use the same Bootstrap theming system, so the key moves under dashboard:

format:
  dashboard:
    theme: united

You don't always need SCSS. Quarto accepts a set of basic options next to theme for quick tweaks:

format:
  html:
    theme: cosmo
    fontsize: 1.1em
    linestretch: 1.7
    max-width: 1100px

This bumps the base font size, adds line spacing (the default is 1.5) and narrows the content area from Bootstrap's 1400px default. Other basic options include mainfont, monofont, fontcolor, linkcolor and backgroundcolor.

Two special values switch Bootstrap off. theme: pandoc gives you Pandoc's plain default HTML styling, and theme: none adds no theme CSS at all, which suits pages you style entirely yourself.

How Do I Add Dark Mode to a Quarto Website?

Give theme a light and a dark key instead of a single name:

format:
  html:
    theme:
      light: flatly
      dark: darkly
    respect-user-color-scheme: true

Quarto builds both stylesheets and adds a toggle in the top right corner of the page. When it can, the toggle stores the reader's choice in browser local storage so it sticks between visits.

Without respect-user-color-scheme, the key you list first sets the default, so the example above opens in light mode. With it set to true, the page follows the reader's operating system or browser setting instead. Per the docs, as of Quarto 1.7 that option needs JavaScript; readers with it disabled see the first theme you listed.

Each mode can take its own list of files, which is how you fix a single detail that looks wrong in dark mode only:

theme:
  light: [cosmo, theme.scss]
  dark: [cosmo, theme-dark.scss]

For content that should change with the mode, such as a logo or a chart image, wrap it in a div with the .light-content or .dark-content class. Quarto hides whichever one doesn't match the current mode. Code blocks follow along too: when your highlight style has light and dark versions, Quarto picks the one that fits.

A complete light and dark setup for a website

Here's a full _quarto.yml you can copy. It pairs Flatly with Darkly, which Bootswatch describes as Flatly in night mode, so fonts and spacing stay put when a reader flips the toggle. It also follows the reader's system setting. Each mode gets one shared SCSS file plus its own small override:

project:
  type: website

website:
  title: "Lab Notes"

format:
  html:
    theme:
      light: [flatly, shared.scss, light.scss]
      dark: [darkly, shared.scss, dark.scss]
    respect-user-color-scheme: true

Put fonts, spacing and anything mode-neutral in shared.scss. Keep light.scss and dark.scss to a handful of color variables each, such as $link-color and $code-block-bg. Because both lists name the shared file, a font change lands in both modes at once, and the per-mode files stay short enough to compare side by side.

Customizing Quarto Themes with SCSS Region Comments

To customize a theme, list it first and your own file after it:

format:
  html:
    theme: [cosmo, custom.scss]

A theme file is ordinary SCSS split into regions by special comments. /*-- scss:defaults --*/ holds Sass variables, and /*-- scss:rules --*/ holds normal CSS rules. Here's a small custom.scss:

/*-- scss:defaults --*/
$primary: #2c6e49 !default;
$font-family-sans-serif: system-ui, -apple-system, "Segoe UI", sans-serif !default;
$code-block-bg: #f3f6f4 !default;

/*-- scss:rules --*/
blockquote {
  border-left: 4px solid $primary;
  padding-left: 1rem;
}

The result is Cosmo with a green accent for links, buttons and the navbar, a system font stack, a pale green code block background and a colored bar on blockquotes.

Three more regions exist for advanced files: scss:uses, scss:functions and scss:mixins. A file needs at least one region comment to be valid, and you can repeat a region; Quarto merges repeats in order.

File order matters, and it works differently for variables and rules. According to More About Quarto Themes, rules are layered in YAML order, but variables are layered in reverse. Your custom.scss variables get set before Cosmo's, and Cosmo declares its values with !default (meaning "only if not already set"), so yours win. Adding !default to your own lines lets a file listed after yours override them in turn.

If you want plain CSS for rendered Markdown outside Quarto, that's a different mechanism. Our Markdown CSS guide covers it. Typora, for example, styles Markdown with plain CSS files, and our Typora themes guide shows how they work.

Quarto Sass Variables Worth Changing First

Bootstrap defines over 1,400 Sass variables, and Quarto adds its own on top. These are the ones that change the most with the least effort:

VariableWhat it controls
$primaryBootstrap accent color, also the navbar's default background
$body-bg / $body-colorPage background and text color
$link-colorLink color
$font-family-sans-serifBody font
$font-family-monospaceCode font
$code-block-bgBackground of fenced code blocks
$code-bg / $code-colorInline code background and text
$navbar-bg / $navbar-fgWebsite navbar colors
$sidebar-bg / $footer-bgSidebar and footer backgrounds
$toc-colorTable of contents text
$callout-color-noteNote callout color (also tip, caution, warning, important)

All of them go in the scss:defaults region, never in YAML. If a variable isn't on Quarto's list, check Bootstrap's own variables file; most of those work too.

Using _brand.yml Alongside Quarto Themes

Since Quarto 1.6, you can describe colors, fonts and logos once in a _brand.yml file at the project root, next to _quarto.yml. Quarto applies it to html, dashboard, revealjs and typst output, per the Brand guide.

color:
  primary: "#2c6e49"
  background: "#fbfbf8"
  foreground: "#1d1d1b"
typography:
  fonts:
    - family: Inter
      source: google
  base: Inter

By default the brand file has the lowest priority, so a Bootswatch theme listed in theme can override it. To make the brand win over the theme, list brand after it: theme: [cosmo, brand, custom.scss].

For dark mode, a brand file can give most colors a light and a dark value, though palette colors can't be split that way yet. Since Quarto 1.7 you can also point the brand key at separate light and dark brand files. Teams that need one look across slides, reports and websites get the most from this route.

How Do I Change the Theme of a Quarto Revealjs Presentation?

Revealjs slides use a separate theme list, so Bootswatch names like cosmo don't apply there. The Reveal Themes page lists twelve names: beige, blood, dark, default, dracula, league, moon, night, serif, simple, sky and solarized.

format:
  revealjs:
    theme: [dark, slides.scss]

The same region comments work here. Slide-specific variables carry a presentation- prefix, such as $presentation-font-size-root (40px by default) and $presentation-heading-font. Other variables, like $body-bg and $link-color, share their names with the HTML ones. CSS rules aimed at slide content usually need the .reveal .slide prefix to beat the theme's own styles.

For writing the slides themselves, see our Markdown slides guide.

Where Quarto Themes Stop: PDF, Word and Markdown Previews

Bootswatch themes and SCSS layering only affect HTML-based output: HTML pages, websites, dashboards, and revealjs with its own list. Typst PDFs pick up colors and fonts from _brand.yml. LaTeX PDFs and Word files ignore Bootswatch entirely; Word styling comes from a reference document set with reference-doc.

Plain Markdown tools don't know about Quarto themes either. That's our limitation too: our editor's preview and its HTML export use their own styling and won't apply Bootswatch, SCSS or _brand.yml. The preview also doesn't render YAML front matter. You can draft the Markdown body in the editor or turn it into a full HTML page with our Markdown to HTML converter. Then run quarto preview to check the themed result.

Quarto Themes FAQ

Quarto themes reward a light touch: pick a Bootswatch base, add a dark partner, and change five or six Sass variables before you reach for custom rules. Keep _brand.yml for styling that has to match across slides, sites and Typst reports. Draft the content itself anywhere you like, such as our free Markdown editor, then let Quarto apply the theme when it renders.