
React projects created using [Create React App](https://create-react-app.dev) or [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) should work out of the box with Preview.js, even if you use CSS-in-JS libraries
such as Styled Components or Emotion.

You can confirm this by testing Preview.js with a simple `<HelloWorld />` component:

<DocImage src="/docs/react-example.png" />

Assuming this works fine, it's time to try Preview.js with other components!

It's important to understand that
not every component will preview successfully, because Preview.js renders them in isolation.

If you try to preview a component that depends on a particular React context or some other global state, it will
crash unless you set up a [`<Wrapper />` component](/docs/config/wrapper) to mock the required parts of your app and set up context providers.

Here are some common examples. You may need to combine them if you use several of these libraries (e.g. React Router + Redux).

## Usage with React Router v5

```tsx
// __previewjs__/Wrapper.tsx

import React from "react";
import { BrowserRouter } from "react-router-dom";
import "../src/index.css";

export const Wrapper = ({ children }) => (
  <BrowserRouter>
    {children}
  </BrowserRouter>
);
```

## Usage with React Router v6

```tsx
// __previewjs__/Wrapper.tsx

import React from "react";
import { RouterProvider, createBrowserRouter } from "react-router-dom";
import "../src/index.css";

export const Wrapper = ({ children }) => (
  <RouterProvider router={createBrowserRouter([{path: '*', element: children}])} />
);
```

## Using Redux

```tsx
// __previewjs__/Wrapper.tsx

import React from "react";
import { Provider } from "react-redux";
import store from "../src/redux";
import "../src/index.css";

export const Wrapper = ({ children }) => (
  <Provider store={store}>
    {children}
  </Provider>
);
```


React


While [Next.js](https://nextjs.org) is based on React, it requires a little extra setup to work perfectly with Preview.js.

In particular, since Preview.js renders components in isolation (and therefore outside of Next.js), they may crash
when you use `<Link />` or `<Image />`, or when you try to access the router with `useRouter()`.

This can be remediated by configuring a [`Wrapper.tsx` file](/docs/config/wrapper) that imports the `@previewjs/config-helper-nextjs` package (which you will need to install):

```tsx
// __previewjs__/Wrapper.tsx

import "../styles/global.css";
import "@previewjs/config-helper-nextjs";
```

## Custom implementation

If you'd like more precise control over how Next.js is mocked, you can start with the following code:

```tsx
// __previewjs__/Wrapper.tsx

import "../styles/global.css";

import * as NextImage from "next/image";
import * as NextRouter from "next/router";

const OriginalNextImage = NextImage.default;

// Patch Image to disable optimisations within Preview.js.
Object.defineProperty(NextImage, "default", {
  configurable: true,
  value: (props: NextImage.ImageProps) => (
    <OriginalNextImage {...props} unoptimized />
  ),
});

// Patch useRouter() to fake the router within Preview.js.
Object.defineProperty(NextRouter, "useRouter", {
  configurable: true,
  value: () => ({
    locale: "en-US",
    route: "/",
    pathname: "/",
    query: {},
    asPath: "/",
    push() {
      return Promise.resolve(true);
    },
    replace() {
      return Promise.resolve(true);
    },
    reload() {},
    back() {},
    prefetch() {
      return Promise.resolve();
    },
    beforePopState() {},
    events: {
      on() {},
      off() {},
      emit() {},
    },
    isFallback: false,
  }),
});
```


Next.js


Preview.js automatically loads your PostCSS config, so Tailwind should just work.

If Tailwind isn't detected automatically, make sure that you have a `postcss.config.js` file (or equivalent), such as:

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

If Tailwind still isn't detected by Preview.js, you may need to [set up a wrapper that imports your global CSS](/docs/config/css).


Tailwind


Preview.js provides first-class support for React, delivering a polished, native experience.

## Guides

- [React guide](./guides/react) - For React 16.14 and above
- [Next.js](./guides/nextjs) - Tips for using Preview.js with Next.js
- [Tailwind CSS](./guides/tailwind) - How to set up Tailwind CSS with Preview.js

## Configuration

Preview.js works out of the box with TypeScript and JSX. For more advanced use cases, check out our configuration guides:

- [CSS configuration](./config/css)
- [Wrapper components](./config/wrapper)


Setup guides

Getting started


Preview.js supports CSS imports out of the box.

You can import CSS files in your components directly:

```tsx
import "./styles.css";
```

You can also import CSS files in your wrapper component to apply global styles:

```tsx
// __previewjs__/Wrapper.tsx
import "../src/styles.css";

export function Wrapper({ children }) {
  return <div>{children}</div>;
}
```

## CSS Modules

CSS Modules are supported out of the box.

```css
/* Button.module.css */
.button {
  background: blue;
  color: white;
}
```

```tsx
import styles from "./Button.module.css";

export function Button() {
  return <button className={styles.button}>Click me</button>;
}
```

## SASS/SCSS

SASS/SCSS is supported out of the box.

```scss
/* styles.scss */
$color: blue;

.button {
  background: $color;
  color: white;
}
```

```tsx
import "./styles.scss";
```

## LESS

LESS is supported out of the box.

```less
/* styles.less */
@color: blue;

.button {
  background: @color;
  color: white;
}
```

```tsx
import "./styles.less";
```

## 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.



You can create a wrapper component that will be used to render every component preview.

This is useful to:
- set up global styles
- set up global context providers
- set up routing
- set up any other global configuration

## Configuration

Create a wrapper component in the `__previewjs__` directory at the root of your project:

```tsx
// __previewjs__/Wrapper.tsx

import { ReactNode } from "react";

export function Wrapper({ children }: { children: ReactNode }) {
  return <div>{children}</div>;
}
```

## Examples

Here are some examples of what you can do with a wrapper component.

### Global styles

```tsx
// __previewjs__/Wrapper.tsx

import { ReactNode } from "react";
import "../src/styles.css";

export function Wrapper({ children }: { children: ReactNode }) {
  return <div>{children}</div>;
}
```

### Context providers

```tsx
// __previewjs__/Wrapper.tsx

import { ReactNode } from "react";
import { ThemeProvider } from "../src/theme";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function Wrapper({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <ThemeProvider>{children}</ThemeProvider>
    </QueryClientProvider>
  );
}
```


Wrapper component


Your components may depend on static assets such as images.

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

```js
import icon from "./icon.svg";
```

If you prefer to use explicit paths instead, you may need to configure a public directory in `preview.config.js`:

```js
// preview.config.js

import { defineConfig } from "@previewjs/config";

export default defineConfig({
  publicDir: "static",
});
```


Static Assets


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

Since Preview.js uses [Vite](https://vitejs.dev/) under the hood, you just need to configure Vite with [`resolve.alias`](https://vitejs.dev/config/shared-options.html#resolve-alias).

For example if you want `ui-components/Button` to map to
`src/ui/components/Button.tsx`, you will need the following configuration:

```js
// vite.config.js

export default {
  resolve: {
    alias: {
      "ui-components": "src/ui/components",
    },
  },
};
```

## js/tsconfig.json support

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


Custom Aliases


Your code may rely 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

import { defineConfig } from "@previewjs/config";
import { svgr } from "vite-plugin-react-svgr";

export default defineConfig({
  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


:::caution Experimental

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

:::

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.

:::
