feat: Add optional line numbers with showLineNumbers option (#61)

Add support for displaying line numbers alongside code blocks with customizable styling and starting line number.

Author: AVGVSTVS96

.changeset/curly-mammals-allow.md

@@ -0,0 +1,5 @@
+---
+"react-shiki": patch
+---
+
+feat: Add support for line numbers with `showLineNumbers`

package/README.md

@@ -23,6 +23,7 @@ A performant client-side syntax highlighting component and hook for React, built
     - [Custom Languages](#custom-languages)
       - [Preloading Custom Languages](#preloading-custom-languages)
     - [Custom Transformers](#custom-transformers)
+    - [Line Numbers](#line-numbers)
   - [Integration](#integration)
     - [Integration with react-markdown](#integration-with-react-markdown)
     - [Handling Inline Code](#handling-inline-code)
@@ -44,6 +45,7 @@ A performant client-side syntax highlighting component and hook for React, built
 - 🖥️ `ShikiHighlighter` component displays a language label for each code block
   when `showLanguage` is set to `true` (default)
 - 🎨 Customizable styling of generated code blocks and language labels
+- 📏 Optional line numbers with customizable starting number and styling
 
 ## Installation
 
@@ -155,6 +157,8 @@ See [Shiki - RegExp Engines](https://shiki.style/guide/regex-engines) for more i
 | `theme`             | `string \| object` | `'github-dark'` | Single or multi-theme configuration, built-in or custom textmate theme object |
 | `delay`             | `number`           | `0`             | Delay between highlights (in milliseconds)                                    |
 | `customLanguages`   | `array`            | `[]`            | Array of custom languages to preload                                          |
+| `showLineNumbers`   | `boolean`          | `false`         | Display line numbers alongside code                                           |
+| `startingLineNumber` | `number`           | `1`             | Starting line number when line numbers are enabled                           |
 | `transformers`      | `array`            | `[]`            | Custom Shiki transformers for modifying the highlighting output               |
 | `cssVariablePrefix` | `string`           | `'--shiki'`     | Prefix for CSS variables storing theme colors                                 |
 | `defaultColor`      | `string \| false`  | `'light'`       | Default theme mode when using multiple themes, can also disable default theme |
@@ -221,12 +225,12 @@ Custom themes can be passed as a TextMate theme in JavaScript object. For exampl
 ```tsx
 import tokyoNight from "../styles/tokyo-night.json";
 
-// Using the component
+// Component
 <ShikiHighlighter language="tsx" theme={tokyoNight}>
   {code.trim()}
 </ShikiHighlighter>
 
-// Using the hook
+// Hook
 const highlightedCode = useShikiHighlighter(code, "tsx", tokyoNight);
 ```
 
@@ -237,12 +241,12 @@ Custom languages should be passed as a TextMate grammar in JavaScript object. Fo
 ```tsx
 import mcfunction from "../langs/mcfunction.tmLanguage.json";
 
-// Using the component
+// Component
 <ShikiHighlighter language={mcfunction} theme="github-dark">
   {code.trim()}
 </ShikiHighlighter>
 
-// Using the hook
+// Hook
 const highlightedCode = useShikiHighlighter(code, mcfunction, "github-dark");
 ```
 
@@ -254,7 +258,7 @@ For dynamic highlighting scenarios where language selection happens at runtime:
 import mcfunction from "../langs/mcfunction.tmLanguage.json";
 import bosque from "../langs/bosque.tmLanguage.json";
 
-// With the component
+// Component
 <ShikiHighlighter
   language="typescript"
   theme="github-dark"
@@ -263,7 +267,7 @@ import bosque from "../langs/bosque.tmLanguage.json";
   {code.trim()}
 </ShikiHighlighter>
 
-// With the hook
+// Hook
 const highlightedCode = useShikiHighlighter(code, "typescript", "github-dark", {
   customLanguages: [mcfunction, bosque],
 });
@@ -274,17 +278,82 @@ const highlightedCode = useShikiHighlighter(code, "typescript", "github-dark", {
 ```tsx
 import { customTransformer } from "../utils/shikiTransformers";
 
-// Using the component
+// Component
 <ShikiHighlighter language="tsx" transformers={[customTransformer]}>
   {code.trim()}
 </ShikiHighlighter>
 
-// Using the hook
+// Hook
 const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
   transformers: [customTransformer],
 });
 ```
 
+### Line Numbers
+
+Display line numbers alongside your code, these are CSS-based
+and can be customized with CSS variables:
+
+```tsx
+// Component
+<ShikiHighlighter 
+  language="javascript"
+  theme="github-dark"
+  showLineNumbers,
+  startingLineNumber={0} // default is 1
+>
+  {code}
+</ShikiHighlighter>
+
+<ShikiHighlighter 
+  language="python" 
+  theme="github-dark" 
+  showLineNumbers 
+  startingLineNumber={0}
+>
+  {code}
+</ShikiHighlighter>
+
+// Hook (import 'react-shiki/css' for line numbers to work)
+const highlightedCode = useShikiHighlighter(code, "javascript", "github-dark", {
+  showLineNumbers: true,
+  startingLineNumber: 0, 
+});
+```
+
+> [!NOTE]
+> When using the hook with line numbers, import the CSS file for the line numbers to work:
+> ```tsx
+> import 'react-shiki/css';
+> ```
+> Or provide your own CSS counter implementation and styles for `.line-numbers` (line `span`) and `.has-line-numbers` (container `code` element)
+
+Available CSS variables for customization:
+```css
+--line-numbers-foreground: rgba(107, 114, 128, 0.5);
+--line-numbers-width: 2ch;
+--line-numbers-padding-left: 0ch;
+--line-numbers-padding-right: 2ch;
+--line-numbers-font-size: inherit;
+--line-numbers-font-weight: inherit;
+--line-numbers-opacity: 1;
+```
+
+You can customize them in your own CSS or by using the style prop on the component:
+```tsx
+<ShikiHighlighter 
+  language="javascript"
+  theme="github-dark"
+  showLineNumbers
+  style={{
+    '--line-numbers-foreground': '#60a5fa',
+    '--line-numbers-width': '3ch'
+  }}
+>
+  {code}
+</ShikiHighlighter>
+```
+
 ## Integration
 
 ### Integration with react-markdown

package/package.json

@@ -26,9 +26,7 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist", "src/lib/styles.css"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -41,7 +39,8 @@
     "./core": {
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
-    }
+    },
+    "./css": "./src/lib/styles.css"
   },
   "scripts": {
     "dev": "tsup --watch",

package/src/__tests__/line-numbers.test.tsx

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import { ShikiHighlighter } from '../index';
+
+describe('Line Numbers', () => {
+  const code = `function test() {
+  return 'hello';
+}`;
+
+  it('should not show line numbers by default', async () => {
+    const { container } = render(
+      <ShikiHighlighter language="javascript" theme="github-dark">
+        {code}
+      </ShikiHighlighter>
+    );
+
+    // Wait for highlighting to complete
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const container_element = container.querySelector('#shiki-container');
+    expect(container_element).not.toHaveClass('has-line-numbers');
+
+    const lineElements = container.querySelectorAll('.line-numbers');
+    expect(lineElements).toHaveLength(0);
+  });
+
+  it('should show line numbers when enabled', async () => {
+    const { container } = render(
+      <ShikiHighlighter
+        language="javascript"
+        theme="github-dark"
+        showLineNumbers
+      >
+        {code}
+      </ShikiHighlighter>
+    );
+
+    // Wait for highlighting to complete
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const codeElement = container.querySelector('code');
+    expect(codeElement).toHaveClass('has-line-numbers');
+
+    const lineElements = container.querySelectorAll('.line-numbers');
+    expect(lineElements.length).toBeGreaterThan(0);
+  });
+
+  it('should set custom starting line number', async () => {
+    const { container } = render(
+      <ShikiHighlighter
+        language="javascript"
+        theme="github-dark"
+        showLineNumbers
+        startingLineNumber={42}
+      >
+        {code}
+      </ShikiHighlighter>
+    );
+
+    // Wait for highlighting to complete
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Check which elements have the style attribute
+    const elementsWithStyle = container.querySelectorAll(
+      '[style*="--line-start"]'
+    );
+    expect(elementsWithStyle.length).toBeGreaterThan(0);
+    expect(elementsWithStyle[0]?.getAttribute('style')).toContain(
+      '--line-start: 42'
+    );
+  });
+
+  it('should not set line-start CSS variable when starting from 1', async () => {
+    const { container } = render(
+      <ShikiHighlighter
+        language="javascript"
+        theme="github-dark"
+        showLineNumbers
+        startingLineNumber={1}
+      >
+        {code}
+      </ShikiHighlighter>
+    );
+
+    // Wait for highlighting to complete
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const elementsWithStyle = container.querySelectorAll(
+      '[style*="--line-start"]'
+    );
+    expect(elementsWithStyle.length).toBe(0);
+  });
+});

package/src/__tests__/performance.bench.ts

@@ -19,9 +19,9 @@ import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
 import htmlReactParser from 'html-react-parser';
 
-import type { Language, Theme, Themes } from '../types';
+import type { Language, Theme, Themes } from '../lib/types';
 
-import { resolveLanguage, resolveTheme } from '../resolvers';
+import { resolveLanguage, resolveTheme } from '../lib/resolvers';
 // --- Test Data ---
 
 // Small code sample (few lines)

package/src/lib/component.tsx

@@ -72,6 +72,18 @@ export interface ShikiHighlighterProps extends HighlighterOptions {
    */
   showLanguage?: boolean;
 
+  /**
+   * Whether to show line numbers
+   * @default false
+   */
+  showLineNumbers?: boolean;
+
+  /**
+   * Starting line number (when showLineNumbers is true)
+   * @default 1
+   */
+  startingLineNumber?: number;
+
   /**
    * The HTML element that wraps the generated code block.
    * @default 'pre'
@@ -104,6 +116,8 @@ export const createShikiHighlighterComponent = (
     className,
     langClassName,
     showLanguage = true,
+    showLineNumbers = false,
+    startingLineNumber = 1,
     children: code,
     as: Element = 'pre',
     customLanguages,
@@ -115,6 +129,8 @@ export const createShikiHighlighterComponent = (
       customLanguages,
       defaultColor,
       cssVariablePrefix,
+      showLineNumbers,
+      startingLineNumber,
       ...shikiOptions,
     };
 

package/src/lib/hook.ts

@@ -31,6 +31,7 @@ import type {
 
 import { throttleHighlighting } from './utils';
 import { resolveLanguage, resolveTheme } from './resolvers';
+import { lineNumbersTransformer } from './transformers';
 
 const DEFAULT_THEMES: Themes = {
   light: 'github-light',
@@ -108,9 +109,14 @@ export const useShikiHighlighter = (
   });
 
   const shikiOptions = useMemo<CodeToHastOptions>(() => {
-    const { defaultColor, cssVariablePrefix, ...restOptions } =
-      stableOpts;
     const languageOption = { lang: languageId };
+    const {
+      defaultColor,
+      cssVariablePrefix,
+      showLineNumbers,
+      startingLineNumber,
+      ...restOptions
+    } = stableOpts;
 
     const themeOptions = isMultiTheme
       ? ({
@@ -122,7 +128,18 @@ export const useShikiHighlighter = (
           theme: singleTheme || DEFAULT_THEMES.dark,
         } as CodeOptionsSingleTheme);
 
-    return { ...languageOption, ...themeOptions, ...restOptions };
+    // Add line numbers transformer if enabled
+    const transformers = restOptions.transformers || [];
+    if (showLineNumbers) {
+      transformers.push(lineNumbersTransformer(startingLineNumber));
+    }
+
+    return {
+      ...languageOption,
+      ...themeOptions,
+      ...restOptions,
+      transformers,
+    };
   }, [languageId, themeId, langRev, themeRev, optsRev]);
 
   useEffect(() => {
@@ -141,9 +158,11 @@ export const useShikiHighlighter = (
 
       // Check if language is loaded, fallback to plaintext if not
       const loadedLanguages = highlighter.getLoadedLanguages();
-      const langToUse = loadedLanguages.includes(languageId) ? languageId : 'plaintext';
+      const langToUse = loadedLanguages.includes(languageId)
+        ? languageId
+        : 'plaintext';
       const finalOptions = { ...shikiOptions, lang: langToUse };
-      
+
       const hast = highlighter.codeToHast(code, finalOptions);
 
       if (isMounted) {

package/src/lib/resolvers.ts

@@ -71,7 +71,7 @@ export const resolveLanguage = (
     };
   }
 
-  // For any other string, pass it through, 
+  // For any other string, pass it through,
   // fallback is handled in highlighter factories
   return {
     languageId: lang,