
<DocVideo src="/videos/platform-cli.mp4" />

:::caution Brand new

Preview.js CLI came out mid-April 2022.

Feel free to report bugs [on GitHub](https://github.com/fwouts/previewjs/issues).

:::

## Installing

Install Preview.js CLI:

```sh
# pnpm
$ pnpm add -D @previewjs/cli

# npm
$ npm install --dev @previewjs/cli

# Yarn
$ yarn add -D @previewjs/cli
```

You can then run `previewjs` in your project directory and pick any component to preview!


Command-line interface


<DocVideo src="/videos/platform-vscode.mp4" />

## Installing

Install Preview.js from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=zenclabs.previewjs) or by searching for "Preview.js" in the **Extensions** panel of Visual Studio Code.


Visual Studio Code

Getting started

Supported Frameworks


<DocVideo src="/videos/platform-intellij.mp4" />

## Installing

Install Preview.js from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/18384-preview-js) or by searching for "Preview.js" in the **Plugins** window of IntelliJ / WebStorm.


IntelliJ / WebStorm

Platforms


Thanks to a strong foundation provided by [Vite](https://vitejs.dev), most CSS-in-JS libraries will work out of the box, as well as plain CSS imports and CSS modules.

However, you may need some minimal set-up for global CSS to work.

## Global CSS

Since Preview.js renders components in isolation, it doesn't run any top-level entry points that you may have set up in your app.

In order to import global CSS, you can set up a wrapper component:

<Tabs>
<Tab name="React">

```tsx
// __previewjs__/Wrapper.tsx

import "../src/index.css";
import React from "react";

export const Wrapper = React.Fragment;
```

</Tab>
<Tab name="Vue 2">

```html
// __previewjs__/Wrapper.vue

<template>
  <slot />
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
<Tab name="Vue 3">

```html
// __previewjs__/Wrapper.vue

<template>
  <slot />
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
</Tabs>

## PostCSS / Tailwind

If your CSS relies on PostCSS, it will be picked up as long as your project has a `postcss.config.js` file.

For example for Tailwind, here is the required configuration:

```js title="/postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

You should also make sure that you import the global CSS as explained above.



By default, each component is rendered in a blank page.

If you rely on your components being rendered in a specific hierarchy such as a padded box or specific React providers, you may want to wrap components instead. 

This is done by creating a Wrapper component. You can also use this file to set up any global variables.

<Tabs>
<Tab name="React">

```tsx
// __previewjs__/Wrapper.tsx

import React from 'react';
import "../src/index.css";

export const Wrapper: React.FC = ({ children }) => (
  <>
    <MyContext.Provider value={...}>
      <div className="wrapped">
        {children}
      </div>
    </MyContext.Provider>
  </>
);
```

</Tab>
<Tab name="Vue 2">

```html
// __previewjs__/Wrapper.vue

<template>
  <div class="wrapped">
    <slot />
  </div>
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
<Tab name="Vue 3">

```html
// __previewjs__/Wrapper.vue

<template>
  <div class="wrapped">
    <slot />
  </div>
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
</Tabs>

You can customise the wrapper's location in `preview.config.js`:

<Tabs>
<Tab name="React">

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  wrapper: {
    path: "src/PreviewWrapper.jsx",
    componentName: "default",
  },
};
```

</Tab>
<Tab name="Vue">

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  wrapper: {
    path: "src/PreviewWrapper.vue",
  },
};
```

</Tab>
</Tabs>
```


Wrapping components


Your components may depend on static assets such as images.

Preview.js automatically lets you import any asset with an `import` statement.

If you prefer to use explicit paths instead, you may need to configure a public directory.

This is done via the `publicDir` property in `preview.config.js`:

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  publicDir: "static",
};
```


Static Assets


If you use custom aliases, you may need to help Preview.js resolve imports.

For example if you use statements such as `import ... from "ui-components/Button"` that should map to
`src/ui/components/Button`, you will need the following configuration:

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  alias: {
    "ui-components": "src/ui/components",
  },
};
```

## Webpack example

If you want to import aliases from Webpack, you could use the following configuration:

```js
// preview.config.js
const webpackConfig = require("./webpack.config");

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  alias: webpackConfig.resolve.alias,
};
```

## TypeScript support

If you use TypeScript, you're in luck.

Preview.js can automatically detect aliases from `tsconfig.json`. As a result, you may not need to explicitly provide aliases.


Custom Aliases


Your code may be relying on SVG files imported as React components, such as:

```js
import { ReactComponent as Logo } from "./logo.svg";
```

In order to make this work, you will need to add a dev dependency on `vite-plugin-react-svgr` (or any other SVGR plugin for Vite) and customise `preview.config.js`:

```js
// preview.config.js
const { svgr } = require("vite-plugin-react-svgr");

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  vite: {
    plugins: [
      svgr({
        exportAs: "ReactComponent",
        // exportAs: "default" if you want `import Logo from "./logo.svg"` instead

        // If you import SVG files via an alias, you'll need to also pass "alias" here.
        // See https://previewjs.com/docs/config/aliases
        //
        // alias: { ... }
      }),
    ],
  },
};
```


SVGR support (React only)


:::caution Experimental

React Native is not officially supported at this stage. Preview.js will only work for a subset of components.

**Requirement:** Preview.js v1.8.0 (VS Code / IntelliJ) or `@previewjs/cli` v1.2.0

:::

You can preview React Native components, as long as they don't depend on `expo` packages. For example, if your component depends directly or indirectly on `expo-web-browser`, it will fail to preview.

**This means that your root App component is unlikely to work with Preview.js.**

## Testing your components with dark theme

In order to force your components to be rendered with the dark color theme, insert the following code in your [Wrapper](/docs/config/wrapper) file.

```tsx
// __previewjs__/Wrapper.tsx

import { Appearance } from "react-native";

Appearance.getColorScheme = () => "dark";
```

:::info Request for contributions

If you're familiar with [Vite](https://vitejs.dev) and find out how to make your React Native Web app with Expo compile, feel free to [open an issue](https://github.com/fwouts/previewjs/issues) sharing your sample repo!

See https://github.com/vitejs/vite/issues/3195 for more context on the issue.

:::


React Native

Configuration


Preview.js lets you specify what properties to pass to your component.

Whenever possible, suitable props will be automatically generated based on detected types.

For example, say that you have the following component in React:

```tsx
export const Button = (props: { label: string; disabled: boolean }) => {
  return <button disabled={props.disabled}>{props.label}</button>;
};
```

The following props will automatically be generated by Preview.js:

```js
properties = {
  label: "label",
  disabled: false,
};
```

This also works for Vue components, including the newer [`<script setup>`](https://vuejs.org/api/sfc-script-setup.html) syntax used in Vue 3.

## See it in action

<Tabs>
  <Tab name="React">
    <DocVideo src="/videos/autogenerated-props-react.mp4" />
  </Tab>
  <Tab name="Vue">
    <DocVideo src="/videos/autogenerated-props-vue.mp4" />
  </Tab>
</Tabs>


Autogenerated props


Preview.js updates your component's preview on every keystroke so you can focus on your code.

No need to press Cmd/Ctrl+S all the time!

## See it in action

<Tabs>
  <Tab name="React">
    <DocVideo src="/videos/instant-refresh-react.mp4" />
  </Tab>
  <Tab name="Vue">
    <DocVideo src="/videos/instant-refresh-vue.mp4" />
  </Tab>
</Tabs>


Instant refresh


You can tell Preview.js to use preset properties for a specific component with a few lines of code:

<Tabs>
<Tab name="React">

```tsx
import { setupPreviews } from "@previewjs/plugin-react/setup";

const MyComponent = ({ label }) => <div>{label}</div>;

setupPreviews(MyComponent, () => ({
  example: {
    label: "Hello, World!",
  },
}));
```

</Tab>
<Tab name="SolidJS">

```tsx
import { setupPreviews } from "@previewjs/plugin-solid/setup";

const MyComponent = ({ label }) => <div>{label}</div>;

setupPreviews(MyComponent, () => ({
  example: {
    label: "Hello, World!",
  },
}));
```

</Tab>
<Tab name="Vue 2">

```html
<template>
  <div>{{ label }}</div>
</template>

<script>
  export default {
    props: {
      label: {
        type: String,
      },
    },
    previews: () => ({
      example: {
        label: "Hello, World!",
      },
    }),
  };
</script>
```

</Tab>
<Tab name="Vue 3">

```html
<script setup lang="ts">
  import { definePreviews } from "@previewjs/plugin-vue3/setup";

  interface Props {
    label?: string;
  }

  defineProps<Props>();

  definePreviews<Props>(() => ({
    example: {
      label: "Hello, World!",
    },
  }));
</script>
<template>
  <div>{{ label }}</div>
</template>
```

</Tab>
</Tabs>

You can set up as many custom previews as you like. Preview.js will let you instantly switch between them.

## See it in action

<Tabs>
  <Tab name="React">
    <DocVideo src="/videos/custom-previews-react.mp4" />
  </Tab>
  <Tab name="Vue">
    <DocVideo src="/videos/custom-previews-vue.mp4" />
  </Tab>
</Tabs>


Custom previews


Preview.js supports the [Component Story Format (v2)](https://storybook.js.org/docs/react/api/csf), in particular `args` and `decorators`.

You can work on stories within Preview.js. No need to wait for Storybook to spin up anymore!

<DocVideo src="/videos/storybook-react.mp4" />

:::caution

Preview.js does not support the legacy `storiesOf()` API.

Storybook addons are ignored when running inside Preview.js.

If you run into any issues, feel free to [open a GitHub issue](https://github.com/fwouts/previewjs/issues).

:::


Storybook


Developing a responsive component? You can pick from a series of preconfigured viewports, or choose your own.

In addition, you can zoom in/out to tweak your component until it's truly pixel-perfect.

## See it in action

<DocVideo src="/videos/viewports-vue.mp4" />


Viewport preview


By default, Preview.js uses a white background. Sometimes, that's not what you want.

You can either set a background color in [your wrapper component](/docs/config/wrapper) or use the dark background toggle available in [Preview.js Pro](/pro).

## See it in action

<DocVideo src="/videos/dark-background-toggle-vue.mp4" />


Dark background toggle


The component picker allows you to switch instantly between components defined in the same file, as well as corresponding Storybook stories.

For example, when `HeroHeader.tsx` defines two components `HeroHeader` and `Title`, and another file `HeroHeader.stories.tsx` defines various Storybook stories for these buttons, you'll be able to switch between all of them without leaving Preview.js.

## See it in action

<DocVideo src="/videos/switcher-react.mp4" />


Component switcher


Preview.js can detect all components in your project, and let you quickly browse through them.

## See it in action

<DocVideo src="/videos/search-react.mp4" />

:::tip
Hit **Cmd/Ctrl+K** to open component search instantly within Preview.js Pro.
:::
