Component Variants

To easily mock a component in a variety of states with type safety you can create multiple variants of a component simply by adding a sibling file using a component’s filename and replacing the the .svelte extension with variants.ts. See this Kitbook’s [SearchResult] page for an example with several different variants.

It’s easiest to create a variants file using the [Viewer], so we won’t give a simple template here, but rather show an example with all the possible options:

Header.variants.ts
ts
import type { Variant, Viewport } from 'kitbook'
import type Component from './Header.svelte'
export const viewports: Viewport[] = [
  { name: 'Desktop', width: 800, height: 600 },
  { name: 'Mobile', width: 320, height: 480 },
]
export const variants: Variant<Component>[] = [
  {
    name: 'Home Page',
    description: 'Displays how the header will look from the home page',
    props: {
      activeURL: '/',
      githubURL: 'https://github.com/jacob-8/kitbook/',
    },
    contexts: [
      {
        key: 'settings',
        context: { foo: 'baz' },
      }
    ],
    slots: {
      default: 'My Workbench' // can pass a string or a Svelte component
      // presently we can only mock the default slot and not named slots until Svelte supports dynamically named slots since Kitbook needs to have the dynamically named slots feature to be able to mock named slots
    }
  },
  {
    name: 'User Dashboard Page',
    props: {
      activeURL: '/dashboard',
      githubURL: 'https://github.com/jacob-8/kitbook/dashboard',
    },
    viewports: [
      { name: 'special', width: 555, height: 432 },
    ],
  }
]

The viewports specified above are completely optional. Viewports are automatically specified at a Kitbook-wide level in your Kitbook config. Then you have the option in each variants file to add viewports applying to each variant. Then if you want further control, you can specificy viewports for a variant just on the variant itself as seen in the second variant above.

Page and Layout Variants

+page.svelte files are just plain Svelte components with a very important data prop. So you can create a variants file for them as well but must replace the + prefix with _ (_page.variants.ts) because + is reserved for SvelteKit files:

_page.variants.ts
ts
import type { Variant } from 'kitbook'
import type Component from './+page.svelte'
export const variants: Variant<Component>[] = [
  {
    name: 'First',
    props: {
      data: {
        // place data props here
      },
    },
  },
]

The same applies to layout files. Just add a _layout.variants.ts file and you’re good to go.

Variant Tips

The wonderful thing about variants is they’re written in TypeScript so you can easily spin up varieties of variants with minimal effort without having to duplicate data. Just use features of the language like ...spread and .map() or import data from mocks folder and apply it across multiple different components.

That will be enough to keep you busy for awhile, but there may come a point where you want to mock something which uses named slots* or perhaps is a composition of components working together. You’ll want to keep reading to learn about [Component Compositions].

Yes, there is a way for Kitbook to dynamically create slots but it’s a bit of hack using Svelte’s internal API and hasn’t been implemented.