Custom Themes

Themes are comprised of a definition and a set of components.

Defining a Theme

Use the defineTheme helper to define a theme. At minimum you must provide componentsPath, an absolute path to the directory containing the theme's components, and we'd recommend providing a config type.

import { defineTheme } from "@kobalte/solidbase/config";

type CustomThemeConfig = {};

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

Components Folder

The folder at componentsPath must contain a Layout file and optionally an mdx-components file. All other files in this directory will be ignored, feel free to organize your components however you'd like.

The Layout file is the runtime entrypoint for the theme and will be rendered by SolidBaseRoot. It must have a component as its default export.

Any named exports from mdx-components will be given to MDXProvider from solid-mdx, making them available in MDX files without needing to be imported. Components with lowercase names will override HTML elements of the same name.

Some exports have special uses:

• DirectiveContainer: Rendered whenever a Markdown directive is encountered.

Vite Plugin

Themes can provide their own Vite plugin by defining a vite function. This function receives the SolidBase config and should return a Vite plugin.

You can use it to conditionally import code based on the provided config, load virtual modules generated by the theme, or anything else you'd want a Vite plugin for.

const customTheme = defineTheme<CustomThemeConfig>({
  ...,
  vite(config: SolidBaseResolvedConfig<CustomThemeConfig>) {
    return {
      ... // a regular Vite plugin
    }
  }
})

Building a Layout

The most basic Layout receives the current route as children and renders it:

import { type RouteSectionProps } from "@solidjs/router";

export default function Layout(props: RouteSectionProps) {
  return <>{props.children}</>;
}

You can use the SolidBase config and each page's metadata to customize the layout via useSolidBaseContext and useCurrentPageData respectively.

Distributing a Custom Theme

SolidBase themes are most easily distributed as npm packages. If using TypeScript, your theme definition must be compiled to JavaScript before publishing. It's up to you whether you distribute your theme's components as TS or JS.

Consuming a Theme

To consume a theme, import its definition in your app.config and use it to create a custom withSolidBase function:

import { someTheme } from "awesome-solidbase-theme";

const withSolidBase = createWithSolidBase(someTheme);

export default defineConfig(withSolidBase(...))

You can add to the theme by extending it with your own theme.