Prism React Renderer

Common errors

• TypeError: Cannot read properties of undefined (reading 'languages')

  cause The Prism instance is not correctly loaded or accessible, often when attempting to highlight a language that isn't registered or if the custom Prism prop is misconfigured.
  fix Ensure the `language` prop is a valid Prism language. If using a custom Prism instance, verify it's correctly passed to the `prism` prop. Check for `prism-react-renderer`'s bundled languages or add custom ones via the escape-hatch.

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.

  cause Often indicates that the `Highlight` component was not imported correctly, or there's a problem with the React environment.
  fix Verify the import statement: `import { Highlight } from 'prism-react-renderer'`. Ensure React and ReactDOM are properly installed and configured for your project.

• Unhandled Rejection (TypeError): theme is undefined

  cause The `theme` prop received an `undefined` value, which can happen if a theme isn't found or loaded correctly.
  fix Use one of the `themes` exported by `prism-react-renderer` (e.g., `themes.shadesOfPurple`) or ensure your custom theme object is valid. Version 2.0.5 fixed a bug where an undefined theme would cause a runtime error, so ensure you are on a recent version if this issue persists.

Warnings

• breaking The `theme dictionary hook` was removed in v2.4.1. If you were using this internal hook, your code will break.
  Fix: Review the changelog for alternative approaches to theme management if you relied on internal APIs.
• breaking Upgrading from v1 to v2 involved significant changes. Specific breaking changes are documented in the upgrade guide.
  Fix: Refer to the 'Upgrading from v1 to v2' section in the package README for a detailed migration path. This often involves changes in how themes are applied or prop structures.
• gotcha Prism React Renderer requires `react` as a peer dependency. Ensure you have `react` installed in your project at a compatible version.
  Fix: Install `react` and `react-dom` if not already present: `npm install react react-dom` or `yarn add react react-dom`.
• gotcha When using custom Prism setups, ensure the `prism` prop is correctly passed to the `Highlight` component to avoid issues with language definitions or tokenization.
  Fix: If using a custom Prism instance, pass it via the `prism` prop: `<Highlight prism={myCustomPrismInstance} ... />`. This is an 'escape-hatch' for advanced use cases.
• gotcha Since v2.4.1, React Server Components (RSC) are supported. If deploying to an RSC environment, ensure your setup is compatible with this change.
  Fix: No specific fix required if your environment supports RSC, but be aware of how components behave in server-side vs. client-side contexts.

Install

• npm install prism-react-renderer npm
• yarn add prism-react-renderer yarn
• pnpm add prism-react-renderer pnpm

Imports

• Highlight
  wrong:

  const { Highlight } = require('prism-react-renderer')

  correct:

  import { Highlight } from 'prism-react-renderer'

  Main component for rendering highlighted code. Primarily used with ESM imports.
• themes
  wrong:

  import themes from 'prism-react-renderer/themes'

  correct:

  import { themes } from 'prism-react-renderer'

  Named export providing built-in themes (e.g., `themes.shadesOfPurple`).
• normalizeTokens

  import { normalizeTokens } from 'prism-react-renderer'

  Utility function for normalizing token arrays, exported since v2.3.1.
• useTokenize

  import { useTokenize } from 'prism-react-renderer'

  Utility hook for tokenizing code, exported since v2.3.1, useful for custom rendering flows.

Quickstart

This quickstart demonstrates how to use the <Highlight /> component with a built-in theme and custom rendering logic.

import React from "react"
import ReactDOM from "react-dom/client"
import { Highlight, themes } from "prism-react-renderer"

const codeBlock = `
const GroceryItem: React.FC<GroceryItemProps> = ({ item }) => {
  return (
    <div>
      <h2>{item.name}</h2>
      <p>Price: {item.price}</p>
      <p>Quantity: {item.quantity}</p>
    </div>
  );
}
`

export const App = () => (
  <Highlight
    theme={themes.shadesOfPurple}
    code={codeBlock}
    language="typescript"
  >
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <pre style={style} className={className}>
        {tokens.map((line, i) => (
          <div {...getLineProps({ line, key: i })}>
            {line.map((token, key) => (
              <span {...getTokenProps({ token, key })} />
            ))}
          </div>
        ))}
      </pre>
    )}
  </Highlight>
);

ReactDOM.createRoot(document.getElementById('root')!).render(<App />)