# React

If you would like to use CKBox in a React application, you can directly use the `CKBox` React component exported by the `@ckbox/core` package. Start by installing the following packages with NPM or an equivalent tool:

```bash
npm install @ckbox/core @ckbox/components
```

If you use CKEditor plugin for CKBox, then additionally install `ckbox` package:

```bash
npm install ckbox
```

> **Note**
>
> Note, that the `@ckbox/core` package requires React 18. If your app is using an older version of React then use the `ckbox` package instead as described in [this guide](../../installation.md#npm).

> **Note**
>
> Please refer to our repo with examples for full [code sample](https://github.com/ckbox-io/ckbox-examples/tree/main/react).

Shown below is the content of an example React component file:

```jsx
import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

// CKEditor plugin for CKBox has an implicit dependency on `ckbox` package.
// Therefore, make sure to install and import it if you use the plugin.
//
// If you don't use CKEditor plugin for CKBox, then `ckbox` package can be omitted.
import "ckbox";

function App() {
	return <CKBox tokenUrl="https://your.token.url" />;
}

export default App;
```

> **Note**
>
> See the list of the supported [configuration options](../../configuration/configuration-options.md) that will help you configure the component.

<a id="category-icons-as-react-components">

## Category icons as React components

When using React, you can easily override the category icons with custom React components in addition to using [icons as plain strings](../../configuration/configuration-options.md#categoriesicons). CKBox styling is injected via the `className` prop.

```jsx
import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

function App() {
	return (
		<CKBox
			categories={{
				icons: {
					Files: ({ className }) => (
						<svg
							xmlns="http://www.w3.org/2000/svg"
							className={className}
							viewBox="0 0 20 20"
						>
							<path d="M6 6V5a3 3 0 013-3h2a3 3 0 013 3v1h2a2 2 0 012 2v3.57A22.952 22.952 0 0110 13a22.95 22.95 0 01-8-1.43V8a2 2 0 012-2h2zm2-1a1 1 0 011-1h2a1 1 0 011 1v1H8V5zm1 5a1 1 0 011-1h.01a1 1 0 110 2H10a1 1 0 01-1-1z" />
							<path d="M2 13.692V16a2 2 0 002 2h12a2 2 0 002-2v-2.308A24.974 24.974 0 0110 15c-2.796 0-5.487-.46-8-1.308z" />
						</svg>
					),
				},
			}}
			tokenUrl="https://your.token.url"
		/>
	);
}

export default App;
```

<a id="legacy-versions-of-react">

## Legacy versions of React

As noted above, `@ckbox/core` package requires React 18 to work correctly and it cannot be used directly with legacy versions of React.

Therefore, if your app is using a pre-18 version of React, then we advise you to use `ckbox` package instead. Since `react` and `react-dom` are transitive dependencies of `ckbox` package, then its UMD build should be used to avoid issues with running multiple versions of React in the same app.

> **Note**
>
> CKBox UMD file is a standalone batteries-included build. More info is available [here](other.md#umd-file).

Start by importing `ckbox` UMD build in your app’s entry file:

```ts
import React from "react";
import ReactDOM from "react-dom";
import App from "./App";

// Import UMD build only once in your app.
// `CKBox` object will be exposed globally.
import "ckbox/dist/ckbox.js";

const app = document.getElementById("app");

ReactDOM.render(
	<React.StrictMode>
		<App />
	</React.StrictMode>,
	app
);
```

`CKBox` object will be exposed globally, so it can be referenced later in components without a direct import:

```ts
import React from "react";

function App() {
	const ref = React.useRef(null);

	React.useEffect(() => {
		const root = ref.current;

		if (!root) {
			return;
		}

		const { unmount } = CKBox.mount(root, {
			dialog: true,
			tokenUrl: "https://your.token.url",
		});

		return () => {
			unmount();
		};
	}, []);

	return <div ref={ref} />;
}

export default App;
```

<a id="server-side-rendering">

## Server-side rendering

While in theory CKBox can be rendered on the server-side, it still relies on client-side features such as [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) during instantation. This might lead to a mismatch between HTML rendered on the server side and the one on the client side, resulting in poorer user experience. Therefore, if your app is using server-side rendering by default, then we advise to opt-out of that feature for CKBox.

<a id="nextjs">

### Next.js

[Next.js](https://nextjs.org/) is one of the most popular React frameworks that employs server-side rendering by default. You can easily integrate CKBox with Next.js by importing it dynamically with **disabled SSR** as shown below:

```ts
import React from "react";
import dynamic from "next/dynamic";
import "@ckbox/components/dist/styles/ckbox.css";

const CKBox = dynamic(() => import("@ckbox/core").then((e) => e.CKBox), {
	ssr: false,
});

export default function Home() {
	return <CKBox dialog={true} tokenUrl="https://your.token.url" />;
}
```

> **Note**
>
> Since Next.js aggressively optimizes production bundle, CKBox might fail on runtime in some scenarios. In order to avoid issues, we advise to opt-out from code-splitting for all `@ckbox/*` packages. Please refer to our repo with examples for full [code sample](https://github.com/ckbox-io/ckbox-examples/tree/main/react-nextjs).

> **Note**
>
> Need more functionality? [Take a survey](https://surveys.hotjar.com/1d72aefc-0073-416d-9e70-b773458881b4) and help us develop CKBox to suit your needs better!

---

Full index of the CKBox documentation: [llms.txt](../../../../llms.txt)