0
# Highlighting Adapters
1

2
The adapter system allows switching between different syntax highlighting engines and provides a flexible architecture for custom highlighting implementations.
3

4
## Capabilities
5

6
### CodeHighlightAdapterProvider
7

8
Provider component for configuring highlighting adapters throughout the component tree.
9

10
```typescript { .api }
11
/**
12
 * Provider component for configuring highlighting adapters
13
 * @param props - Provider configuration
14
 * @returns Provider component wrapping children
15
 */
16
function CodeHighlightAdapterProvider(props: CodeHighlightAdapterProviderProps): JSX.Element;
17

18
interface CodeHighlightAdapterProviderProps {
19
  /** Highlighting adapter to use */
20
  adapter: CodeHighlightAdapter;
21
  /** Child components that will use the adapter */
22
  children: React.ReactNode;
23
}
24

25
interface CodeHighlightAdapter {
26
  /** Optional function to load highlighting context (e.g., async library loading) */
27
  loadContext?: () => Promise<any>;
28
  /** Function that returns a highlighter function given the loaded context */
29
  getHighlighter: (ctx: any) => Highlighter;
30
}
31

32
type Highlighter = (input: HighlighterInput) => HighlighterOutput;
33

34
interface HighlighterInput {
35
  /** Current color scheme */
36
  colorScheme: 'light' | 'dark';
37
  /** Code to highlight */
38
  code: string;
39
  /** Programming language for syntax highlighting */
40
  language?: string;
41
}
42

43
interface HighlighterOutput {
44
  /** Highlighted code (html markup) */
45
  highlightedCode: string;
46
  /** true if the code is represented with html string, false for plain text string */
47
  isHighlighted: boolean;
48
  /** Props to pass down to <code> tag */
49
  codeElementProps?: Record<string, any>;
50
}
51
```
52

53
**Usage Example:**
54

55
```typescript
56
import { 
57
  CodeHighlightAdapterProvider, 
58
  createHighlightJsAdapter,
59
  CodeHighlight 
60
} from "@mantine/code-highlight";
61
import hljs from 'highlight.js';
62

63
function App() {
64
  const adapter = createHighlightJsAdapter(hljs);
65
  
66
  return (
67
    <CodeHighlightAdapterProvider adapter={adapter}>
68
      <CodeHighlight code="console.log('hello');" language="javascript" />
69
    </CodeHighlightAdapterProvider>
70
  );
71
}
72
```
73

74
### useHighlight Hook
75

76
Hook to access the current highlighting function from context.
77

78
```typescript { .api }
79
/**
80
 * Hook to access the current highlighting function from context
81
 * @returns Current highlighter function or plain text fallback
82
 */
83
function useHighlight(): Highlighter;
84
```
85

86
**Usage Example:**
87

88
```typescript
89
import { useHighlight } from "@mantine/code-highlight";
90

91
function CustomHighlightComponent({ code, language }: { code: string; language?: string }) {
92
  const highlight = useHighlight();
93
  
94
  const result = highlight({
95
    code,
96
    language,
97
    colorScheme: 'light'
98
  });
99
  
100
  if (result.isHighlighted) {
101
    return <pre dangerouslySetInnerHTML={{ __html: result.highlightedCode }} />;
102
  }
103
  
104
  return <pre>{result.highlightedCode}</pre>;
105
}
106
```
107

108
### Highlight.js Adapter
109

110
Creates an adapter for the highlight.js syntax highlighting library.
111

112
```typescript { .api }
113
/**
114
 * Creates an adapter for the highlight.js syntax highlighting library
115
 * @param hljs - Configured highlight.js instance
116
 * @returns CodeHighlightAdapter for highlight.js
117
 */
118
function createHighlightJsAdapter(hljs: any): CodeHighlightAdapter;
119
```
120

121
**Usage Example:**
122

123
```typescript
124
import { CodeHighlightAdapterProvider, createHighlightJsAdapter } from "@mantine/code-highlight";
125
import hljs from 'highlight.js';
126
import 'highlight.js/styles/github.css'; // Import a theme
127

128
// Configure highlight.js
129
hljs.configure({
130
  languages: ['javascript', 'typescript', 'python', 'css', 'html']
131
});
132

133
function App() {
134
  const hljsAdapter = createHighlightJsAdapter(hljs);
135
  
136
  return (
137
    <CodeHighlightAdapterProvider adapter={hljsAdapter}>
138
      {/* All CodeHighlight components will use highlight.js */}
139
      <YourAppComponents />
140
    </CodeHighlightAdapterProvider>
141
  );
142
}
143
```
144

145
### Shiki Adapter
146

147
Creates an adapter for the Shiki syntax highlighting library with advanced theme support.
148

149
```typescript { .api }
150
/**
151
 * Creates an adapter for the Shiki syntax highlighting library
152
 * @param loadShiki - Function that loads and returns configured Shiki instance
153
 * @param options - Configuration options for the adapter
154
 * @returns CodeHighlightAdapter for Shiki
155
 */
156
function createShikiAdapter(
157
  loadShiki: () => Promise<any>,
158
  options?: CreateShikiAdapterOptions
159
): CodeHighlightAdapter;
160

161
interface CreateShikiAdapterOptions {
162
  /** Force a specific color scheme instead of following the theme */
163
  forceColorScheme?: 'dark' | 'light';
164
}
165

166
/**
167
 * Utility function to strip pre/code wrapper elements from Shiki output
168
 * @param data - HTML string from Shiki
169
 * @returns Cleaned HTML string without wrapper elements
170
 */
171
function stripShikiCodeBlocks(data: string): string;
172
```
173

174
**Usage Example:**
175

176
```typescript
177
import { CodeHighlightAdapterProvider, createShikiAdapter } from "@mantine/code-highlight";
178
import { createHighlighter } from 'shiki';
179

180
async function loadShiki() {
181
  const highlighter = await createHighlighter({
182
    themes: ['github-light', 'github-dark'],
183
    langs: ['javascript', 'typescript', 'python', 'css']
184
  });
185
  return highlighter;
186
}
187

188
function App() {
189
  const shikiAdapter = createShikiAdapter(loadShiki, {
190
    // Optional: force dark theme regardless of system preference
191
    forceColorScheme: 'dark'
192
  });
193
  
194
  return (
195
    <CodeHighlightAdapterProvider adapter={shikiAdapter}>
196
      <YourAppComponents />
197
    </CodeHighlightAdapterProvider>
198
  );
199
}
200

201
// Using stripShikiCodeBlocks utility
202
import { stripShikiCodeBlocks } from "@mantine/code-highlight";
203

204
const rawShikiOutput = '<pre class="shiki"><code>console.log("hello");</code></pre>';
205
const cleanedOutput = stripShikiCodeBlocks(rawShikiOutput);
206
// Result: 'console.log("hello");'
207
```
208

209
### Plain Text Adapter
210

211
Default adapter that provides no syntax highlighting, useful as a fallback.
212

213
```typescript { .api }
214
/**
215
 * Default plain text adapter that provides no highlighting
216
 * Used as fallback when no other adapter is configured
217
 */
218
const plainTextAdapter: CodeHighlightAdapter;
219
```
220

221
**Usage Example:**
222

223
```typescript
224
import { CodeHighlightAdapterProvider, plainTextAdapter } from "@mantine/code-highlight";
225

226
// Explicitly use plain text (no highlighting)
227
function PlainTextApp() {
228
  return (
229
    <CodeHighlightAdapterProvider adapter={plainTextAdapter}>
230
      <CodeHighlight code="const x = 1;" language="javascript" />
231
      {/* Code will be displayed without syntax highlighting */}
232
    </CodeHighlightAdapterProvider>
233
  );
234
}
235
```
236

237
## Adapter Implementation
238

239
To create a custom adapter:
240

241
```typescript
242
import type { CodeHighlightAdapter } from "@mantine/code-highlight";
243

244
// Example: Custom adapter with basic keyword highlighting
245
const customAdapter: CodeHighlightAdapter = {
246
  // Optional: Load external dependencies
247
  loadContext: async () => {
248
    // Load highlighting libraries, themes, etc.
249
    return await import('my-highlighter');
250
  },
251
  
252
  // Required: Return highlighter function
253
  getHighlighter: (ctx) => {
254
    return ({ code, language, colorScheme }) => {
255
      if (!ctx || !language) {
256
        return { highlightedCode: code, isHighlighted: false };
257
      }
258
      
259
      const highlighted = ctx.highlight(code, language, colorScheme);
260
      return {
261
        highlightedCode: highlighted,
262
        isHighlighted: true,
263
        codeElementProps: { className: `hljs ${language}` }
264
      };
265
    };
266
  }
267
};
268
```