0
# Component and Hooks
1

2
Core React component and hooks for syntax highlighting with flexible render props pattern and fine-grained control over tokenization and styling.
3

4
## Capabilities
5

6
### Highlight Component
7

8
Main React component that provides syntax highlighting through a render props pattern. Handles tokenization, theme application, and provides helper functions for rendering.
9

10
```typescript { .api }
11
/**
12
 * Main syntax highlighting component using render props pattern
13
 * @param props - Component props including code, language, theme, and render function
14
 * @returns JSX element returned by the children render function
15
 */
16
interface HighlightProps {
17
  /** Optional Prism instance (defaults to bundled Prism) */
18
  prism?: PrismLib;
19
  /** Optional theme (defaults to vsDark) */
20
  theme?: PrismTheme;
21
  /** Programming language for syntax highlighting */
22
  language: Language;
23
  /** Code string to highlight */
24
  code: string;
25
  /** Render function that receives highlighting data and helper functions */
26
  children: (props: RenderProps) => JSX.Element;
27
}
28

29
declare const Highlight: React.FC<HighlightProps>;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { Highlight, themes } from "prism-react-renderer";
36

37
// Basic usage with custom rendering
38
<Highlight
39
  theme={themes.oceanicNext}
40
  code="const greeting = 'Hello, World!';"
41
  language="javascript"
42
>
43
  {({ className, style, tokens, getLineProps, getTokenProps }) => (
44
    <pre className={className} style={style}>
45
      {tokens.map((line, i) => (
46
        <div key={i} {...getLineProps({ line })}>
47
          {line.map((token, key) => (
48
            <span key={key} {...getTokenProps({ token })} />
49
          ))}
50
        </div>
51
      ))}
52
    </pre>
53
  )}
54
</Highlight>
55

56
// With line numbers
57
<Highlight
58
  theme={themes.vsDark}
59
  code={multiLineCode}
60
  language="typescript"
61
>
62
  {({ className, style, tokens, getLineProps, getTokenProps }) => (
63
    <pre className={className} style={style}>
64
      {tokens.map((line, i) => (
65
        <div key={i} {...getLineProps({ line, className: "line" })}>
66
          <span className="line-number">{i + 1}</span>
67
          {line.map((token, key) => (
68
            <span key={key} {...getTokenProps({ token })} />
69
          ))}
70
        </div>
71
      ))}
72
    </pre>
73
  )}
74
</Highlight>
75

76
// With custom Prism instance
77
<Highlight
78
  prism={customPrismInstance}
79
  theme={themes.github}
80
  code={code}
81
  language="python"
82
>
83
  {({ tokens, getLineProps, getTokenProps, className, style }) => (
84
    <pre className={`custom ${className}`} style={style}>
85
      {/* render implementation */}
86
    </pre>
87
  )}
88
</Highlight>
89
```
90

91
### useTokenize Hook
92

93
React hook for tokenizing code using Prism.js. Provides direct access to the tokenization process for custom highlighting implementations.
94

95
```typescript { .api }
96
/**
97
 * Hook to tokenize code using Prism.js with memoization
98
 * @param options - Tokenization options including prism instance, code, grammar, and language
99
 * @returns 2D array of tokens organized by lines
100
 */
101
interface TokenizeOptions {
102
  /** Prism instance to use for tokenization */
103
  prism: PrismLib;
104
  /** Code string to tokenize */
105
  code: string;
106
  /** Optional grammar for the language (if available) */
107
  grammar?: PrismGrammar;
108
  /** Language identifier */
109
  language: Language;
110
}
111

112
declare function useTokenize(options: TokenizeOptions): Token[][];
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { useTokenize, Prism } from "prism-react-renderer";
119

120
function CustomHighlighter({ code, language }) {
121
  const tokens = useTokenize({
122
    prism: Prism,
123
    code,
124
    language,
125
    grammar: Prism.languages[language]
126
  });
127

128
  return (
129
    <div className="custom-highlighter">
130
      {tokens.map((line, lineIndex) => (
131
        <div key={lineIndex} className="code-line">
132
          {line.map((token, tokenIndex) => (
133
            <span 
134
              key={tokenIndex}
135
              className={`token ${token.types.join(' ')}`}
136
              data-empty={token.empty}
137
            >
138
              {token.content}
139
            </span>
140
          ))}
141
        </div>
142
      ))}
143
    </div>
144
  );
145
}
146

147
// Using with custom grammar handling
148
function AdvancedHighlighter({ code, language }) {
149
  const grammar = Prism.languages[language.toLowerCase()];
150
  const tokens = useTokenize({
151
    prism: Prism,
152
    code,
153
    language,
154
    grammar
155
  });
156

157
  if (!grammar) {
158
    console.warn(`Grammar not found for language: ${language}`);
159
  }
160

161
  // Custom rendering logic
162
  return <div>{/* render tokens */}</div>;
163
}
164
```
165

166
### Render Props Helper Functions
167

168
The Highlight component provides helper functions through its render props to generate properly styled props for line and token elements. These functions are only available within the children render function of the Highlight component.
169

170
**getLineProps Function:**
171

172
```typescript { .api }
173
/**
174
 * Function to generate props for line elements with proper styling and CSS classes
175
 * Available in the RenderProps passed to Highlight children function
176
 */
177
type GetLineProps = (input: LineInputProps) => LineOutputProps;
178
```
179

180
**getTokenProps Function:**
181

182
```typescript { .api }
183
/**
184
 * Function to generate props for token elements with proper styling and CSS classes
185
 * Available in the RenderProps passed to Highlight children function
186
 */
187
type GetTokenProps = (input: TokenInputProps) => TokenOutputProps;
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { Highlight, themes } from "prism-react-renderer";
194

195
// Basic usage of helper functions from render props
196
function CodeBlock({ code, language }) {
197
  return (
198
    <Highlight theme={themes.vsDark} code={code} language={language}>
199
      {({ className, style, tokens, getLineProps, getTokenProps }) => (
200
        <pre className={className} style={style}>
201
          {tokens.map((line, i) => {
202
            // Use getLineProps to generate proper line attributes
203
            const lineProps = getLineProps({
204
              line,
205
              className: "my-custom-line",
206
              style: { padding: "0.25rem 0" }
207
            });
208
            
209
            return (
210
              <div key={i} {...lineProps}>
211
                {line.map((token, key) => {
212
                  // Use getTokenProps to generate proper token attributes
213
                  const tokenProps = getTokenProps({
214
                    token,
215
                    className: "my-custom-token"
216
                  });
217
                  
218
                  return <span key={key} {...tokenProps} />;
219
                })}
220
              </div>
221
            );
222
          })}
223
        </pre>
224
      )}
225
    </Highlight>
226
  );
227
}
228

229
// Advanced usage with conditional styling
230
function AdvancedCodeBlock({ code, language, showLineNumbers }) {
231
  return (
232
    <Highlight theme={themes.oceanicNext} code={code} language={language}>
233
      {({ className, style, tokens, getLineProps, getTokenProps }) => (
234
        <pre className={className} style={style}>
235
          {tokens.map((line, i) => {
236
            const lineProps = getLineProps({
237
              line,
238
              className: showLineNumbers ? "line-with-number" : "line"
239
            });
240
            
241
            return (
242
              <div key={i} {...lineProps}>
243
                {showLineNumbers && (
244
                  <span className="line-number">{i + 1}</span>
245
                )}
246
                {line.map((token, key) => (
247
                  <span key={key} {...getTokenProps({ token })} />
248
                ))}
249
              </div>
250
            );
251
          })}
252
        </pre>
253
      )}
254
    </Highlight>
255
  );
256
}
257

258
## Supporting Types
259

260
```typescript { .api }
261
interface RenderProps {
262
  /** 2D array of tokens organized by lines */
263
  tokens: Token[][];
264
  /** CSS class name for the container */
265
  className: string;
266
  /** Inline styles for the container */
267
  style: CSSProperties;
268
  /** Function to generate props for line elements */
269
  getLineProps: (input: LineInputProps) => LineOutputProps;
270
  /** Function to generate props for token elements */
271
  getTokenProps: (input: TokenInputProps) => TokenOutputProps;
272
}
273

274
interface TokenizeOptions {
275
  /** Prism instance to use for tokenization */
276
  prism: PrismLib;
277
  /** Code string to tokenize */
278
  code: string;
279
  /** Optional grammar for the language (if available) */
280
  grammar?: PrismGrammar;
281
  /** Language identifier */
282
  language: Language;
283
}
284
```