Extending Themes

If you'd like to customise an existing theme, you can define a custom theme that extends it. The custom theme's Layout should render the original theme's Layout component, but apart from that you can treat it as a regular theme.

info

The theme used for these docs extends the default theme to add OpenGraph tags!

Creating Extended Themes

These examples will extend the default theme as an example.

Define a custom theme with defineTheme and provide the original theme's definition to extends:

import { defineTheme } from "@kobalte/solidbase/config";
import defaultTheme from "@kobalte/solidbase/default-theme";

const customTheme = defineTheme<CustomThemeConfig>({
  componentsPath: import.meta.resolve("./custom-theme"),
  extends: defaultTheme
});

Add a Layout file inside the componentsPath folder that renders the original theme's Layout:

import { Layout } from "@kobalte/solidbase/default-theme/Layout";

export default function (props: ComponentProps<typeof Layout>) {
  // do whatever and render whatever you want as long as `Layout` gets rendered

  return <Layout {...props} />
}

Extending the Default Theme

The default theme provides multiple methods of customisation, which we'd recommend configuring with a custom theme that extends it.

Customising CSS

The default theme's CSS can be customised using CSS variables:

import Layout from "@kobalte/solidbase/default-theme/Layout";
// this import must be below the Layout import
import "./custom.css";

export default function () { ... };

html {
  --sb-background-color: white;
}

html[data-theme*="dark"] {
  --sb-background-color: black;
}

The full list of overridable CSS variables is in the default theme's source code.

Using Different Fonts

The default theme uses a few fonts:

Lexend for headings
Inter for text
JetBrains Mono for code

To stop these fonts from being loaded, set themeConfig.fonts to false:

export default defineConfig(withSolidBase(
  ...,
  {
    themeConfig: {
      fonts: false
    }
  }
))

You can then provide your own fonts:

html {
  --sb-font-headings: "Comic Sans";
  --sb-font-text: "Comic Sans";
  --sb-font-mono: "Comic Sans";
}

Overriding Components

In addition to using a custom mdx-components file to override the components available in markdown files, the components listed here can be overriden using DefaultThemeComponentsProvider. Most of these components are used as part of the layout, rather than inside your markdown files.

import Layout from "@kobalte/solidbase/default-theme/Layout";
import { DefaultThemeComponentsProvider } from "@kobalte/solidbase/default-theme/context.js";
import Article from "@kobalte/solidbase/default-theme/components/Article";

export default function (props: ComponentProps<typeof Layout>) {
  return (
    <DefaultThemeComponentsProvider
      components={{ Article: CustomArticle }}
    >
      <Layout {...props} />
    </DefaultThemeComponentsProvider>
  )
}

function CustomArticle(props: ComponentProps<typeof Article>) {
  return (
    <Article {...props}>
      {/* Will appear inside the page's <article>, above markdown content */}
      <span>We love SolidBase!</span>
      {props.children}
    </Article>
  )
}

Last updated: 4/17/25, 3:42 AM

Edit this page on GitHub