{"id":11838,"library":"react-refractor","title":"React Refractor - Syntax Highlighter","description":"react-refractor is a lightweight React component for syntax highlighting code snippets, acting as a thin wrapper around the `refractor` library. `refractor` itself is a virtual DOM implementation of `Prism.js`, allowing for efficient updates and server-side rendering without direct DOM manipulation. The current stable version is v4.0.0, which dropped Node.js 18 support and upgraded to `refractor` v5. The library maintains a moderately active release cadence, with several minor and major versions released within the last year. A key differentiator is its VDOM-based approach, which makes it performant and flexible for React environments but also means it's incompatible with `Prism.js` plugins. Developers must explicitly import and register specific language syntaxes from `refractor` to keep bundle sizes small, and styling is left to the developer, often by importing `Prism.js` themes. It requires React 18+ and is ESM-only since v3.0.0.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/rexxars/react-refractor","tags":["javascript","react","highlight","syntax","refractor","vdom","typescript"],"install":[{"cmd":"npm install react-refractor","lang":"bash","label":"npm"},{"cmd":"yarn add react-refractor","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-refractor","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core UI library for which react-refractor is a component wrapper.","package":"react","optional":false},{"reason":"The underlying syntax highlighting engine, a VDOM implementation of Prism.js.","package":"refractor","optional":false}],"imports":[{"note":"Since v3.0.0, react-refractor is ESM-only and uses named exports. Default imports will not work.","wrong":"import Refractor from 'react-refractor'","symbol":"Refractor","correct":"import { Refractor } from 'react-refractor'"},{"note":"Required to register specific language grammars imported from the underlying 'refractor' package.","wrong":"const { registerLanguage } = require('react-refractor')","symbol":"registerLanguage","correct":"import { registerLanguage } from 'react-refractor'"},{"note":"Language grammars are imported directly from the `refractor/lang/` path, not from `react-refractor` itself, and are typically default exports from those specific files.","wrong":"import { javascript } from 'refractor'","symbol":"Language modules (e.g., javascript)","correct":"import js from 'refractor/lang/javascript'"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { Refractor, registerLanguage } from 'react-refractor';\n\n// Import desired languages from 'refractor' and register them\nimport js from 'refractor/lang/javascript';\nimport php from 'refractor/lang/php';\nimport css from 'refractor/lang/css';\n\nregisterLanguage(js);\nregisterLanguage(php);\nregisterLanguage(css);\n\n// A simple PrismJS theme can be included for basic styling\n// This would typically be imported from a CSS file like: import 'prismjs/themes/prism-dark.css';\n// For demonstration, we'll just show the component usage.\n\nfunction App() {\n  const jsCode = `\nconst greet = (name) => {\n  console.log('Hello, ' + name + '!');\n};\ngreet('World');\n`;\n\n  const phpCode = `\n<?php\n  $name = \"PHP\";\n  echo \"Hello, \" . $name . \"!\";\n?>\n`;\n\n  return (\n    <div>\n      <h2>JavaScript Example</h2>\n      <Refractor language=\"javascript\" value={jsCode} />\n\n      <h2>PHP Example</h2>\n      <Refractor language=\"php\" value={phpCode} />\n\n      <p>Note: Stylesheets are not automatically handled; apply your own Prism.js-compatible theme.</p>\n    </div>\n  );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root') || document.createElement('div'));\nroot.render(<App />);","lang":"typescript","description":"This quickstart demonstrates how to install `react-refractor`, register multiple language syntaxes (JavaScript, PHP, CSS) from `refractor`, and render code snippets using the `Refractor` component. It highlights the explicit language registration process and the component's basic usage with `language` and `value` props."},"warnings":[{"fix":"Upgrade Node.js environment to version 20 or higher. Ensure `refractor` v5 is compatible with your project if you're directly interacting with it.","message":"Version 4.0.0 drops support for Node.js versions 18 and below, requiring Node.js 20 or higher. It also upgrades the underlying `refractor` dependency to v5.0.0.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your project to use ES Modules (`import ... from '...'`) or ensure your build system correctly handles ESM. Update all imports from `import Refractor from 'react-refractor'` to `import { Refractor } from 'react-refractor'`.","message":"Since v3.0.0, `react-refractor` is an ESM-only module, meaning it cannot be imported using CommonJS `require()` statements. All exports are named exports, so default imports are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your React installation to version 18 or newer. Ensure your project's build targets ES6 or newer.","message":"Version 3.0.0 and above explicitly require React 18 or higher. It also dropped ES5 compatibility, requiring an ES6-compatible environment.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If `Prism.js` plugin functionality is crucial, `react-refractor` might not be the right choice. Consider alternative highlighting libraries that directly integrate `Prism.js`.","message":"Due to `react-refractor`'s VDOM-based approach, which differs from `Prism.js`'s direct DOM manipulation, you cannot use existing `Prism.js` plugins. This is a fundamental architectural difference.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Import a Prism.js-compatible CSS theme (e.g., from `prismjs/themes`) into your project. You can also customize your own CSS to target the classes generated by `refractor`.","message":"The library does not provide any default styling. You are responsible for importing a compatible stylesheet, typically a Prism.js theme, to make the highlighted code visible and aesthetically pleasing.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Refactor your imports to use ES Modules syntax: `import { Refractor } from 'react-refractor';`. Ensure your project's `package.json` has `\"type\": \"module\"` or your build system handles ESM correctly.","cause":"Attempting to import `react-refractor` using CommonJS `require()` syntax in a Node.js or older environment after v3.0.0.","error":"Error: require() of ES Module node_modules/react-refractor/index.js from ... not supported."},{"fix":"Change your import statement to use named exports: `import { Refractor } from 'react-refractor';`.","cause":"Using a default import (`import Refractor from 'react-refractor'`) when `react-refractor` has switched to named exports since v3.0.0.","error":"TypeError: (0 , react_refractor__WEBPACK_IMPORTED_MODULE_2__.Refractor) is not a function"},{"fix":"Import the required language module (e.g., `import js from 'refractor/lang/javascript';`) and then register it: `registerLanguage(js);`.","cause":"The specific language grammar (e.g., 'javascript') was not imported from `refractor/lang/` and registered with `registerLanguage()` before being used by the `Refractor` component.","error":"Error: No language registered for \"javascript\" (or any other language name)"}],"ecosystem":"npm"}