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:

npm install @ckbox/core @ckbox/components

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

npm install ckbox

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

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;

# 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. CKBox styling is injected via the className prop.

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;

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

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

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:

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;

# Server-side rendering

While in theory CKBox can be rendered on the server-side, it still relies on client-side features such as 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.

# Next.js

Next.js 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:

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" />;
}