0
# Mantine Code Highlight
1

2
Mantine Code Highlight is a React component library for syntax highlighting that provides both block and inline code highlighting with full theme integration. Built for the Mantine ecosystem, it offers flexible highlighting adapters including highlight.js and Shiki, expandable code blocks, copy-to-clipboard functionality, and tabbed interfaces for multiple code files.
3

4
## Package Information
5

6
- **Package Name**: @mantine/code-highlight
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/core @mantine/hooks @mantine/code-highlight`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  CodeHighlight,
16
  InlineCodeHighlight,
17
  CodeHighlightTabs,
18
  CodeHighlightControl,
19
  CodeHighlightAdapterProvider,
20
  createHighlightJsAdapter,
21
  createShikiAdapter,
22
  stripShikiCodeBlocks,
23
  plainTextAdapter,
24
  useHighlight
25
} from "@mantine/code-highlight";
26

27
// Type imports
28
import type {
29
  CodeHighlightFactory,
30
  CodeHighlightProps,
31
  CodeHighlightStylesNames,
32
  CodeHighlightCssVariables,
33
  InlineCodeHighlightFactory,
34
  InlineCodeHighlightProps,
35
  InlineCodeHighlightStylesNames,
36
  InlineCodeHighlightCssVariables,
37
  CodeHighlightTabsFactory,
38
  CodeHighlightTabsProps,
39
  CodeHighlightTabsStylesNames,
40
  CodeHighlightTabsCode,
41
  CodeHighlightDefaultLanguage,
42
  CodeHighlightControlProps
43
} from "@mantine/code-highlight";
44
```
45

46
For CommonJS:
47

48
```javascript
49
const { 
50
  CodeHighlight,
51
  InlineCodeHighlight, 
52
  CodeHighlightTabs
53
} = require("@mantine/code-highlight");
54
```
55

56
### CSS Imports
57

58
```typescript
59
// Required CSS imports for styling
60
import "@mantine/code-highlight/styles.css";
61

62
// Alternative layer-based CSS import
63
import "@mantine/code-highlight/styles.layer.css";
64
```
65

66
## Basic Usage
67

68
```typescript
69
import { CodeHighlight, InlineCodeHighlight } from "@mantine/code-highlight";
70

71
// Block code highlighting
72
function App() {
73
  return (
74
    <CodeHighlight
75
      code={`function hello() {
76
  console.log("Hello, world!");
77
}`}
78
      language="javascript"
79
      withCopyButton
80
    />
81
  );
82
}
83

84
// Inline code highlighting
85
function InlineExample() {
86
  return (
87
    <p>
88
      Use <InlineCodeHighlight code="console.log()" language="js" /> to print.
89
    </p>
90
  );
91
}
92
```
93

94
## Architecture
95

96
Mantine Code Highlight is built around several key components:
97

98
- **Core Components**: `CodeHighlight`, `InlineCodeHighlight`, and `CodeHighlightTabs` for different display modes
99
- **Provider System**: `CodeHighlightAdapterProvider` and `useHighlight` hook for configuring highlighting engines
100
- **Adapter System**: Pluggable highlighting engines (highlight.js, Shiki, plain text) via adapter pattern
101
- **Theme Integration**: Full integration with Mantine's styling system including CSS variables and theme colors
102
- **Control System**: Extensible control components for copy, expand/collapse, and custom actions
103

104
## Capabilities
105

106
### Code Block Highlighting
107

108
Primary component for displaying syntax-highlighted code blocks with extensive customization options.
109

110
```typescript { .api }
111
interface CodeHighlightProps extends 
112
  CodeHighlightSettings,
113
  BoxProps,
114
  StylesApiProps<CodeHighlightFactory>,
115
  ElementProps<'div'> {
116
  /** Code to highlight */
117
  code: string;
118
  /** Language of the code, used for syntax highlighting */
119
  language?: string;
120
  
121
  // Internal props (generally not used directly)
122
  __withOffset?: boolean;
123
  __staticSelector?: string;
124
  __inline?: boolean;
125
}
126

127
function CodeHighlight(props: CodeHighlightProps): JSX.Element;
128
```
129

130
[Code Block Highlighting](./code-highlighting.md)
131

132
### Inline Code Highlighting
133

134
Component for highlighting short code snippets within text content.
135

136
```typescript { .api }
137
interface InlineCodeHighlightProps {
138
  code: string;
139
  language?: string;
140
  background?: MantineColor;
141
  radius?: MantineRadius;
142
  withBorder?: boolean;
143
}
144

145
function InlineCodeHighlight(props: InlineCodeHighlightProps): JSX.Element;
146
```
147

148
[Inline Code Highlighting](./inline-highlighting.md)
149

150
### Tabbed Code Interface
151

152
Component for displaying multiple code files in a tabbed interface.
153

154
```typescript { .api }
155
interface CodeHighlightTabsCode {
156
  language?: string;
157
  code: string;
158
  fileName?: string;
159
  icon?: React.ReactNode;
160
}
161

162
interface CodeHighlightTabsProps {
163
  code: CodeHighlightTabsCode[];
164
  getFileIcon?: (fileName: string) => React.ReactNode;
165
  defaultActiveTab?: number;
166
  activeTab?: number;
167
  onTabChange?: (tab: number) => void;
168
  // Inherits all CodeHighlightSettings properties
169
}
170

171
function CodeHighlightTabs(props: CodeHighlightTabsProps): JSX.Element;
172
```
173

174
[Tabbed Code Interface](./code-tabs.md)
175

176
### Highlighting Adapters
177

178
System for configuring and switching between different syntax highlighting engines.
179

180
```typescript { .api }
181
interface CodeHighlightAdapter {
182
  loadContext?: () => Promise<any>;
183
  getHighlighter: (ctx: any) => Highlighter;
184
}
185

186
function CodeHighlightAdapterProvider(props: {
187
  adapter: CodeHighlightAdapter;
188
  children: React.ReactNode;
189
}): JSX.Element;
190

191
function useHighlight(): Highlighter;
192

193
function createHighlightJsAdapter(hljs: any): CodeHighlightAdapter;
194

195
function createShikiAdapter(
196
  loadShiki: () => Promise<any>,
197
  options?: { forceColorScheme?: 'dark' | 'light' }
198
): CodeHighlightAdapter;
199
```
200

201
[Highlighting Adapters](./adapters.md)
202

203
### Custom Controls
204

205
System for adding custom controls to code highlight components.
206

207
```typescript { .api }
208
interface CodeHighlightControlProps {
209
  children?: React.ReactNode;
210
  tooltipLabel?: string;
211
}
212

213
function CodeHighlightControl(props: CodeHighlightControlProps): JSX.Element;
214
```
215

216
[Custom Controls](./custom-controls.md)
217

218
## Common Types
219

220
```typescript { .api }
221
type MantineColor = string;
222
type MantineRadius = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | string;
223

224
interface CodeHighlightSettings {
225
  copyLabel?: string;
226
  copiedLabel?: string;
227
  defaultExpanded?: boolean;
228
  expanded?: boolean;
229
  onExpandedChange?: (expanded: boolean) => void;
230
  maxCollapsedHeight?: number | string;
231
  withCopyButton?: boolean;
232
  withExpandButton?: boolean;
233
  expandCodeLabel?: string;
234
  collapseCodeLabel?: string;
235
  background?: MantineColor;
236
  radius?: MantineRadius;
237
  withBorder?: boolean;
238
  controls?: React.ReactNode[];
239
  codeColorScheme?: 'dark' | 'light';
240
}
241

242
type Highlighter = (input: {
243
  colorScheme: 'light' | 'dark';
244
  code: string;
245
  language?: string;
246
}) => {
247
  highlightedCode: string;
248
  isHighlighted: boolean;
249
  codeElementProps?: Record<string, any>;
250
};
251

252
// Factory Types
253
type CodeHighlightFactory = Factory<{
254
  props: CodeHighlightProps;
255
  ref: HTMLDivElement;
256
  stylesNames: CodeHighlightStylesNames;
257
  vars: CodeHighlightCssVariables;
258
  staticComponents: {
259
    Control: typeof CodeHighlightControl;
260
  };
261
}>;
262

263
type InlineCodeHighlightFactory = Factory<{
264
  props: InlineCodeHighlightProps;
265
  ref: HTMLElement;
266
  stylesNames: InlineCodeHighlightStylesNames;
267
  vars: InlineCodeHighlightCssVariables;
268
}>;
269

270
type CodeHighlightTabsFactory = Factory<{
271
  props: CodeHighlightTabsProps;
272
  ref: HTMLDivElement;
273
  stylesNames: CodeHighlightTabsStylesNames;
274
}>;
275

276
// Styles Names Types
277
type CodeHighlightStylesNames =
278
  | 'codeHighlight'
279
  | 'pre'
280
  | 'code'
281
  | 'control'
282
  | 'controlTooltip'
283
  | 'controls'
284
  | 'scrollarea'
285
  | 'showCodeButton';
286

287
type InlineCodeHighlightStylesNames = 'inlineCodeHighlight';
288

289
type CodeHighlightTabsStylesNames =
290
  | 'root'
291
  | 'files'
292
  | 'file'
293
  | 'fileIcon'
294
  | 'filesScrollarea'
295
  | CodeHighlightStylesNames;
296

297
// CSS Variables Types
298
type CodeHighlightCssVariables = {
299
  codeHighlight: '--ch-max-height' | '--ch-background' | '--ch-radius';
300
};
301

302
type InlineCodeHighlightCssVariables = {
303
  inlineCodeHighlight: '--ch-background' | '--ch-radius';
304
};
305

306
// Default Language Type
307
type CodeHighlightDefaultLanguage = 'tsx' | 'scss' | 'html' | 'bash' | 'json';
308
```