Skip to content
Starlight

CSS & Styling

You can style your Starlight site with custom CSS files or use the Starlight Tailwind plugin.

Custom CSS styles

Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.

  1. Add a CSS file to your src/ directory. For example, you could set a wider default column width and larger text size for page titles:

    src/styles/custom.css
    :root {
      --sl-content-width: 50rem;
      --sl-text-5xl: 3.5rem;
    }

  2. Add the path to your CSS file to Starlight’s customCss array in astro.config.mjs:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    

    export default defineConfig({
      integrations: [
        starlight({
          title: 'Docs With Custom CSS',
          customCss: [
            // Relative path to your custom CSS file
            './src/styles/custom.css',
          ],
        }),
      ],
    });

You can see all the CSS custom properties used by Starlight that you can set to customize your site in the props.css file on GitHub.

Tailwind CSS

Tailwind CSS support in Astro projects is provided by the Astro Tailwind integration. Starlight provides a complementary Tailwind plugin to help configure Tailwind for compatibility with Starlight’s styles.

The Starlight Tailwind plugin applies the following configuration:

  • Configures Tailwind’s dark: variants to work with Starlight’s dark mode.
  • Uses Tailwind theme colors and fonts in Starlight’s UI.
  • Disables Tailwind’s Preflight reset styles while selectively restoring essential parts of Preflight required for Tailwind’s border utility classes.

Create a new project with Tailwind

Start a new Starlight project with Tailwind CSS pre-configured using create astro:

Terminal window
npm create astro@latest -- --template starlight/tailwind

Add Tailwind to an existing project

If you already have a Starlight site and want to add Tailwind CSS, follow these steps.

  1. Add Astro’s Tailwind integration:

    Terminal window
    npx astro add tailwind

  2. Install the Starlight Tailwind plugin:

    Terminal window
    npm install @astrojs/starlight-tailwind

  3. Create a CSS file for Tailwind’s base styles, for example at src/tailwind.css:

    src/tailwind.css
    @tailwind base;
    @tailwind components;
    @tailwind utilities;

  4. Update your Astro config file to use your Tailwind base styles and disable the default base styles:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    import tailwind from '@astrojs/tailwind';
    

    export default defineConfig({
      integrations: [
        starlight({
          title: 'Docs with Tailwind',
          customCss: [
            // Path to your Tailwind base styles:
            './src/tailwind.css',
          ],
        }),
        tailwind({
          // Disable the default base styles:
          applyBaseStyles: false,
        }),
      ],
    });

  5. Add the Starlight Tailwind plugin to tailwind.config.mjs:

    tailwind.config.mjs
    import starlightPlugin from '@astrojs/starlight-tailwind';
    

    /** @type {import('tailwindcss').Config} */
    export default {
      content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
      plugins: [starlightPlugin()],
    };

Styling Starlight with Tailwind

Starlight will use values from your Tailwind theme config in its UI.

If set, the following options will override Starlight’s default styles:

  • colors.accent — used for links and current item highlighting
  • colors.gray — used for background colors and borders
  • fontFamily.sans — used for UI and content text
  • fontFamily.mono — used for code examples
tailwind.config.mjs
import starlightPlugin from '@astrojs/starlight-tailwind';
import colors from 'tailwindcss/colors';


/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      colors: {
        // Your preferred accent color. Indigo is closest to Starlight’s defaults.
        accent: colors.indigo,
        // Your preferred gray scale. Zinc is closest to Starlight’s defaults.
        gray: colors.zinc,
      },
      fontFamily: {
        // Your preferred text font. Starlight uses a system font stack by default.
        sans: ['"Atkinson Hyperlegible"'],
        // Your preferred code font. Starlight uses system monospace fonts by default.
        mono: ['"IBM Plex Mono"'],
      },
    },
  },
  plugins: [starlightPlugin()],
};

Theming

Starlight’s color theme can be controlled by overriding its default custom properties. These variables are used throughout the UI with a range of gray shades used for text and background colors and an accent color used for links and to highlight current items in navigation.

Color theme editor

Use the sliders below to modify Starlight’s accent and gray color palettes. The dark and light preview areas will show the resulting colors, and the whole page will also update to preview your changes.

Use the Contrast Level option to specify which of the Web Content Accessibility Guideline colour contrast standards to meet.

When you’re happy with your changes, copy the CSS or Tailwind code below and use it in your project.

Presets
Contrast Level
Accent
Gray

Dark mode

Body text is displayed in a gray shade with a high contrast with the background. Links are colored. Some text, like the table of contents, has a lower contrast. Inline code has a distinct background.

Light mode

Body text is displayed in a gray shade with a high contrast with the background. Links are colored. Some text, like the table of contents, has a lower contrast. Inline code has a distinct background.

Add the following CSS to your project in a custom CSS file to apply this theme to your site.