Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rexxars/react-refractor
Syntax highlighter for React based on Prism/refractor, utilizing VDOM for efficient updates
https://github.com/rexxars/react-refractor
Last synced: 6 days ago
JSON representation
Syntax highlighter for React based on Prism/refractor, utilizing VDOM for efficient updates
- Host: GitHub
- URL: https://github.com/rexxars/react-refractor
- Owner: rexxars
- License: mit
- Created: 2018-04-29T14:52:28.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-06-16T13:50:00.000Z (8 months ago)
- Last Synced: 2025-01-29T00:49:19.508Z (14 days ago)
- Language: TypeScript
- Homepage: https://rexxars.github.io/react-refractor/
- Size: 2.32 MB
- Stars: 72
- Watchers: 2
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fe-resources - react-refractor
README
# react-refractor
Syntax highlighter for React, utilizing VDOM for efficient updates
[](http://browsenpm.org/package/react-refractor)
- Thin wrapper on top of [refractor](https://github.com/wooorm/refractor) (Syntax highlighting using VDOM)
- refractor uses [Prism](https://github.com/PrismJS/prism) under the hood, thus supports all the same syntaxes
- About 14kB minified + gziped when using a single language syntax. Languages tend to add a bit of weight, see [unpkg](https://unpkg.com/refractor/lang/) for some pointers on how much.
Feel free to check out a [super-simple demo](http://rexxars.github.io/react-refractor/).
## Installation
This package is [ESM only][esm] and requires React 18 or higher.
```
npm install --save react-refractor
```
## Usage
```js
import {Refractor, registerLanguage} from 'react-refractor'
// Load any languages you want to use from `refractor`
import js from 'refractor/lang/javascript.js'
import php from 'refractor/lang/php.js'
// Then register them
registerLanguage(js)
registerLanguage(php)
ReactDOM.render(
,
document.getElementById('target'),
)
```
You'll need to register the languages you want to use - I've intentionally left all languages out of the default bundle in order to reduce the bundle size out of the box. Load and register them from [refractor](https://unpkg.com/refractor/lang/) using something like this:
```ts
import docker from 'refractor/lang/docker'
registerLanguage(docker)
```
## Styling
Stylesheets are **not** automatically handled for you - but there is [a bunch of premade themes](https://github.com/PrismJS/prism/tree/gh-pages/themes) for Prism which you can simply drop in and they'll "just work". You can either grab these from the source, of pull them in using a CSS loader - whatever works best for you. You can also download a customized stylesheet from Prism's [download customizer](http://prismjs.com/download.html).
Note that when using the `markers` feature, there is an additional class name called `refractor-marker` which is not defined by Prism, as it's not a part of its feature set. You can either set it yourself, or you can explicitly set class names on markers.
## Props
| Name | Description |
| :---------- | :------------------------------------------------------------------------------------ |
| `className` | Class name for the outermost `pre` tag. Default: `refractor` |
| `language` | Language to use for syntax highlighting this value. Must be registered prior to usage |
| `value` | The code snippet to syntax highlight |
| `inline` | Whether code should be displayed inline (no `
` tag, sets `display: inline`) |
| `markers` | Array of lines to mark. See section on markers below |
| `plainText` | Set to `true` to skip highlighting and render the passed value as-is |
## Differences to Prism
Prism.js operates directly on the DOM, while refractor generates an AST which react-refractor walks over and converts into virtual DOM nodes. The benefit of the AST approach is that we can easily reuse this across different platforms, highlight on both the server and the client using the same code base and benefit from Reacts virtual DOM diff algorithm to only update the nodes that change.
The drawback to this approach is that you cannot use Prism plugins, since they _also_ work and depend directly on the DOM.
## Markers
It's quite common to want to highlight lines when doing syntax highlighting, but Prism uses a very DOM-centric approach to achieve this. In order to make up for this, react-refractor provides a custom plugin that lets you define "markers". Since this is a non-standard feature, you will have to provide your own styling for the `refractor-marker` class name. To highlight lines, simply provide the line numbers in the `markers` property:
```js
const source = `
const foo = 'bar'
const bar = 'foo'
const baz = foo + bar
`
// Highlight line 1 and 2, but not 3
```
You are also able to provide greater customization by specifying an object for each marker, which can include either a `className` or a `component` property. This allows you to render basically anything you want:
```js
const source = `
const foo = 'bar'
const bar = 'foo'
const baz = "bar" + bar
`
// Highlight line 1 and 2, but not 3
(
{props.children}
)}
]}
/>
```
## License
MIT-licensed. See LICENSE.
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c