0
# React Syntax Highlighter
1

2
React Syntax Highlighter is a comprehensive React component library that provides syntax highlighting capabilities for displaying code in web applications. It supports multiple syntax highlighting engines including highlight.js and Prism.js through lowlight and refractor AST parsers, offering developers flexibility in choosing their preferred highlighting approach.
3

4
## Package Information
5

6
- **Package Name**: react-syntax-highlighter
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install react-syntax-highlighter`
10

11
## Core Imports
12

13
```javascript
14
import SyntaxHighlighter from 'react-syntax-highlighter';
15
import { docco } from 'react-syntax-highlighter/dist/esm/styles/hljs';
16
```
17

18
For Prism.js support:
19

20
```javascript
21
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
22
import { dark } from 'react-syntax-highlighter/dist/esm/styles/prism';
23
```
24

25
For Light builds (manual language registration):
26

27
```javascript
28
import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
29
import js from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
30
import docco from 'react-syntax-highlighter/dist/esm/styles/hljs/docco';
31

32
SyntaxHighlighter.registerLanguage('javascript', js);
33
```
34

35
## Basic Usage
36

37
```javascript
38
import React from 'react';
39
import SyntaxHighlighter from 'react-syntax-highlighter';
40
import { docco } from 'react-syntax-highlighter/dist/esm/styles/hljs';
41

42
const CodeBlock = () => {
43
  const codeString = `function greet(name) {
44
  return \`Hello, \${name}!\`;
45
}
46

47
console.log(greet('World'));`;
48

49
  return (
50
    <SyntaxHighlighter language="javascript" style={docco}>
51
      {codeString}
52
    </SyntaxHighlighter>
53
  );
54
};
55
```
56

57
## Architecture
58

59
React Syntax Highlighter is built around several key components:
60

61
- **Multiple Build Variants**: Full, Light, and Async builds for different bundle size requirements
62
- **Dual Engine Support**: Both highlight.js (via lowlight) and Prism.js (via refractor) syntax engines
63
- **JavaScript Styling**: Inline styles eliminating external CSS dependencies
64
- **AST-Based Rendering**: Uses syntax trees to build virtual DOM instead of dangerouslySetInnerHTML
65
- **Dynamic Language Loading**: Async variants support on-demand language loading
66
- **Extensible Rendering**: Custom renderers and virtualization support
67

68
## Capabilities
69

70
### Standard Syntax Highlighter
71

72
Full-featured syntax highlighter using highlight.js with pre-bundled languages and default styling.
73

74
```javascript { .api }
75
function SyntaxHighlighter(props: SyntaxHighlighterProps): JSX.Element;
76

77
interface SyntaxHighlighterProps {
78
  language?: string;
79
  children: string;
80
  style?: { [key: string]: React.CSSProperties };
81
  customStyle?: React.CSSProperties;
82
  useInlineStyles?: boolean;
83
  showLineNumbers?: boolean;
84
  showInlineLineNumbers?: boolean;
85
  startingLineNumber?: number;
86
  lineNumberContainerStyle?: React.CSSProperties;
87
  lineNumberStyle?: React.CSSProperties | ((lineNumber: number) => React.CSSProperties);
88
  wrapLines?: boolean;
89
  wrapLongLines?: boolean;
90
  lineProps?: React.HTMLProps<HTMLElement> | ((lineNumber: number) => React.HTMLProps<HTMLElement>);
91
  renderer?: (props: RendererProps) => React.ReactNode;
92
  PreTag?: React.ComponentType<any> | string;
93
  CodeTag?: React.ComponentType<any> | string;
94
  codeTagProps?: React.HTMLProps<HTMLElement>;
95
  [key: string]: any;
96
}
97
```
98

99
[Standard Highlighter](./standard-highlighter.md)
100

101
### Light Build Variants
102

103
Lightweight versions requiring manual language registration for optimal bundle sizes.
104

105
```javascript { .api }
106
// Light build using highlight.js
107
const Light: SyntaxHighlighterComponent & {
108
  registerLanguage: (name: string, language: any) => void;
109
};
110

111
// Light build using Prism.js
112
const PrismLight: SyntaxHighlighterComponent & {
113
  registerLanguage: (name: string, language: any) => void;
114
};
115
```
116

117
[Light Build Variants](./light-builds.md)
118

119
### Async Build Variants
120

121
Asynchronous versions with dynamic language loading and code splitting support.
122

123
```javascript { .api }
124
// Async light build using highlight.js
125
const LightAsync: React.ComponentType<SyntaxHighlighterProps> & {
126
  preload: () => Promise<void>;
127
  loadLanguage: (language: string) => Promise<void>;
128
  isSupportedLanguage: (language: string) => boolean;
129
  isRegistered: (language: string) => boolean;
130
  registerLanguage: (name: string, language: any) => void;
131
  supportedLanguages: string[];
132
};
133

134
// Async variants for Prism.js
135
const PrismAsync: typeof LightAsync;
136
const PrismAsyncLight: typeof LightAsync;
137
```
138

139
[Async Build Variants](./async-builds.md)
140

141
### Prism.js Integration
142

143
Full Prism.js support with enhanced language coverage including JSX, TSX, and modern syntax.
144

145
```javascript { .api }
146
const Prism: SyntaxHighlighterComponent & {
147
  supportedLanguages: string[];
148
};
149

150
const PrismLight: SyntaxHighlighterComponent & {
151
  registerLanguage: (name: string, language: any) => void;
152
  alias: (name: string, aliases: string | string[]) => void;
153
};
154
```
155

156
[Prism Integration](./prism-integration.md)
157

158
### Styling and Themes
159

160
Extensive theme support with JavaScript-based styling and CSS class alternatives.
161

162
```javascript { .api }
163
// Import highlight.js themes
164
import { 
165
  docco, 
166
  github, 
167
  monokai, 
168
  dracula,
169
  solarizedLight,
170
  solarizedDark
171
} from 'react-syntax-highlighter/dist/esm/styles/hljs';
172

173
// Import Prism themes
174
import { 
175
  prism, 
176
  dark, 
177
  tomorrow, 
178
  okaidia,
179
  coy
180
} from 'react-syntax-highlighter/dist/esm/styles/prism';
181
```
182

183
[Styling and Themes](./styling-themes.md)
184

185
### Language Support
186

187
Comprehensive language support with over 472 language definitions across both engines (193 for highlight.js, 279 for Prism.js).
188

189
```javascript { .api }
190
// Access supported languages
191
const supportedLanguages: string[];
192

193
// Import individual languages for light builds
194
import javascript from 'react-syntax-highlighter/dist/esm/languages/hljs/javascript';
195
import python from 'react-syntax-highlighter/dist/esm/languages/hljs/python';
196
import jsx from 'react-syntax-highlighter/dist/esm/languages/prism/jsx';
197
```
198

199
[Language Support](./language-support.md)
200

201
## Types
202

203
```javascript { .api }
204
interface RendererProps {
205
  rows: RowData[];
206
  stylesheet: { [key: string]: React.CSSProperties };
207
  useInlineStyles: boolean;
208
}
209

210
interface RowData {
211
  type: 'element';
212
  tagName: string;
213
  properties: {
214
    className?: string[];
215
    style?: React.CSSProperties;
216
    key?: string;
217
  };
218
  children: Array<RowData | TextNode>;
219
}
220

221
interface TextNode {
222
  type: 'text';
223
  value: string;
224
}
225

226
type SyntaxHighlighterComponent = React.ComponentType<SyntaxHighlighterProps>;
227
```