• Advanced Usage
  • Hooks


If you want to build a new component or you want to re-implement the code editor, for example, you can still rely on the sandpack state and create your UI from scratch.

The sandpack-react package exports a set of hooks, that give you access to the sandpack context in your own components.


The main hook is called useSandpack and gives you the entire context object to play with.


Keep in mind that the useSandpack hook only works inside the <SandpackProvider>.

Let's build a code viewer component that renders a standard pre tag:

import { useSandpack } from "@codesandbox/sandpack-react";
const SimpleCodeViewer = () => {
  const { sandpack } = useSandpack();
  const { files, activeFile } = sandpack;
  const code = files[activeFile].code;
  return <pre>{code}</pre>;

The sandpack object is available in any component and exposes all the internal state:

  • the files including all the setup/template files
  • the activeFile / visibleFiles fields
  • the error object, if any
  • multiple functions for changing the state of sandpack: updateCurrentFile, setActiveFile, etc.

In the component above, you get the active code string by calling files[activeFile].code, so any change of state will trigger a re-render of the component and an update of the code.

We can test this with the CustomSandpack we implemented at the previous step.

<SandpackProvider template="react">
    <SandpackCodeEditor />
    {/* This will render the pre on the right side of your sandpack component */}
    <SimpleCodeViewer />

If you run this, you will notice that the SimpleCodeViewer is in sync with the state of the SandpackCodeEditor.

useSandpack also exports dispatch and listen, you can levarage these functions for communicating directly with the bundler. However, at this point, you'd have understood all the different types of messages and payloads that are passed from the sandpack manager to the iframe and back.

import { useSandpack } from "@codesandbox/sandpack-react";
const CustomRefreshButton = () => {
  const { dispatch, listen } = useSandpack();
  const handleRefresh = () => {
    // sends the refresh message to the bundler, should be logged by the listener
    dispatch({ type: "refresh" });
  useEffect(() => {
    // listens for any message dispatched between sandpack and the bundler
    const stopListening = listen((msg) => console.log(msg));
    return () => {
      // unsubscribe
  }, [listen]);
  return (
    <button type="button" onClick={handleRefresh}>

Plus, useSandpack exposes a bunch of methods that you can use to manage the current state of the Sandpack instance:

closeFileClose the given path in the editor
deleteFileDelete the given path in the editor
dispatchSends a message to the bundler
listenListens for messages from the bundler
openFileOpen the given path in the editor
resetAllFilesReset all files for all paths to the original state
resetFileReset the code for a given path
setActiveFileSet a specific file as active in a given path
updateFileUpdate the content of a file in a given path or multiple files
updateCurrentFileUpdate the content of the current file


Some of the common functionalities of sandpack are also extracted into specialized hooks. These all use useSandpack under the hood, but abstract away the shape of the state object and the dispatch/listen functions.

The refresh button can be built with the useSandpackNavigation hook:

import { useSandpackNavigation } from "@codesandbox/sandpack-react";
const CustomRefreshButton = () => {
  const { refresh } = useSandpackNavigation();
  return (
    <button type="button" onClick={() => refresh()}>
      Refresh Sandpack


We implemented the SandpackCodeEditor on top of codemirror/next, but it is super easy to switch to your favorite code editor. Let's connect the sandpack state to an instance of AceEditor. You can use the useActiveCode hook, which gives you the code value and the updateCode callback.

import { useActiveCode } from "@codesandbox/sandpack-react";
import AceEditor from "react-ace";
import "ace-builds/src-noconflict/mode-javascript";
import "ace-builds/src-noconflict/theme-textmate";
const CustomAceEditor = () => {
  const { code, updateCode } = useActiveCode();
  return (

Now, let's put all of these custom components together:

export const CustomSandpack = () => (
  <SandpackProvider template="react">
    <CustomAceEditor />
    <SandpackPreview showRefreshButton={false} showOpenInCodeSandbox={false} />
    <CustomRefreshButton />
    <CustomOpenInCSB />

It's not pretty, but with just a few lines of code, you can create a whole new component that uses the power of sandpack, but has all the UI and functionality you need for your specific use case.


The SandpackConsole is implemented on top of this hook, which provides an interface to consume the logs from a specific sandpack client. Sandpack runs the console directly into the iframe. As a result, all console messages pass through the Sandpack protocol, where you can attach a listener to these messages in your own component or just use this hook.

const { logs, reset } = useSandpackConsole();


It registers a new sandpack client and returns its instance, listeners, and dispatch function. Using it when creating a custom component to interact directly with the client is recommended. For other cases, use useSandpack instead.


It exposes the theme object configured on SandpackContext and contains an id to ensure uniqueness for custom themes. This theme object is responsible for distributing all the style configurations for the component thee.


It returns the transpile module from the bundler, the same one evaluated inside it.