react-shiki/dist/component-mMdHg8JD.d.ts

Syntax highlighter component for react using shiki

import { Highlighter, HighlighterCore, CodeOptionsMultipleThemes, BundledTheme, CodeToHastOptions, BundledHighlighterOptions, StringLiteralUnion, BundledLanguage, SpecialLanguage, ThemeRegistrationAny } from 'shiki';
import { ReactNode } from 'react';
import { LanguageRegistration as LanguageRegistration$1 } from 'shiki/core';
import { Element as Element$1 } from 'hast';

/**
 * Attribution:
 *  This code was written by github:hippotastic in expressive-code/expressive-code
 *  https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-shiki/src/languages.ts
 */

type IShikiRawRepository = LanguageRegistration$1['repository'];
type IShikiRawRule = IShikiRawRepository[keyof IShikiRawRepository];
type ILocation = IShikiRawRepository['$vscodeTextmateLocation'];
interface ILocatable {
    readonly $vscodeTextmateLocation?: ILocation;
}
interface IRawRepositoryMap {
    [name: string]: IRawRule;
}
type IRawRepository = IRawRepositoryMap & ILocatable;
interface IRawCapturesMap {
    [captureId: string]: IRawRule;
}
type IRawCaptures = IRawCapturesMap & ILocatable;
interface IRawRule extends Omit<IShikiRawRule, 'applyEndPatternLast' | 'captures' | 'patterns'> {
    readonly applyEndPatternLast?: boolean | number;
    readonly captures?: IRawCaptures;
    readonly comment?: string;
    readonly patterns?: IRawRule[];
}
/**
 * A less strict version of Shiki's `LanguageRegistration` interface that aligns better with
 * actual grammars found in the wild. This version attempts to reduce the amount
 * of type errors that would occur when importing and adding external grammars,
 * while still being supported by the language processing code.
 */
interface LanguageRegistration extends Omit<LanguageRegistration$1, 'repository'> {
    repository?: IRawRepository;
}

/**
 * HTML Element, use to type `node` from react-markdown
 */
type Element = Element$1;
/**
 * A Shiki BundledLanguage or a custom textmate grammar object
 * @see https://shiki.style/languages
 */
type Language = LanguageRegistration | StringLiteralUnion<BundledLanguage | SpecialLanguage> | undefined;
/**
 * A Shiki BundledTheme or a custom textmate theme object
 * @see https://shiki.style/themes
 */
type Theme = ThemeRegistrationAny | StringLiteralUnion<BundledTheme>;
/**
 * A map of color names to themes.
 * This allows you to specify multiple themes for the generated code.
 * Supports custom textmate theme objects in addition to Shiki's bundled themes
 *
 * @example
 * ```ts
 * useShikiHighlighter(code, language, {
 *   light: 'github-light',
 *   dark: 'github-dark',
 *   dim: 'github-dark-dimmed'
 * })
 * ```
 *
 * @see https://shiki.style/guide/dual-themes
 */
type Themes = {
    [key: string]: ThemeRegistrationAny | StringLiteralUnion<BundledTheme>;
};
/**
 * Configuration options specific to react-shiki
 */
interface ReactShikiOptions {
    /**
     * Minimum time (in milliseconds) between highlight operations.
     * @default undefined (no throttling)
     */
    delay?: number;
    /**
     * Custom textmate grammars to be preloaded for highlighting.
     */
    customLanguages?: LanguageRegistration | LanguageRegistration[];
    /**
     * Output format for the highlighted code.
     * - 'react': Returns React nodes (default, safer)
     * - 'html': Returns HTML string (~15-45% faster, requires dangerouslySetInnerHTML)
     * @default 'react'
     */
    outputFormat?: 'react' | 'html';
    /**
     * Custom Shiki highlighter instance to use instead of the default one.
     * Keeps bundle small by only importing specified languages/themes.
     * Can be either a Highlighter or HighlighterCore instance.
     *
     * @example
     * import {
     *   createHighlighterCore,
     *   createOnigurumaEngine,
     *   useShikiHighlighter
     * } from "react-shiki";
     *
     * const customHighlighter = await createHighlighterCore({
     *   themes: [
     *     import('@shikijs/themes/nord')
     *   ],
     *   langs: [
     *     import('@shikijs/langs/javascript'),
     *     import('@shikijs/langs/typescript')
     *   ],
     *   engine: createOnigurumaEngine(import('shiki/wasm'))
     * });
     *
     * const highlightedCode = useShikiHighlighter(code, language, theme, {
     *   highlighter: customHighlighter,
     * });
     */
    highlighter?: Highlighter | HighlighterCore;
    /**
     * Whether to show line numbers
     * @default false
     */
    showLineNumbers?: boolean;
    /**
     * Starting line number (when showLineNumbers is true)
     * @default 1
     */
    startingLineNumber?: number;
}
/**
 * Configuration options for the syntax highlighter
 * Extends CodeToHastOptions to allow passing any Shiki options directly
 */
interface HighlighterOptions extends ReactShikiOptions, Pick<CodeOptionsMultipleThemes<BundledTheme>, 'defaultColor' | 'cssVariablePrefix'>, Omit<CodeToHastOptions, 'lang' | 'theme' | 'themes'>, Pick<BundledHighlighterOptions<string, string>, 'langAlias' | 'engine'> {
}
/**
 * Public API signature for the useShikiHighlighter hook.
 */
type UseShikiHighlighter = (code: string, lang: Language, themeInput: Theme | Themes, options?: HighlighterOptions) => ReactNode | string | null;

/**
 * Rehype plugin to add an 'inline' property to <code> elements
 * Sets 'inline' property to true if the <code> is not within a <pre> tag
 *
 * Pass this plugin to the `rehypePlugins` prop of react-markdown
 * You can then access `inline` as a prop in components passed to react-markdown
 *
 * @example
 * <ReactMarkdown rehypePlugins={[rehypeInlineCodeProperty]} />
 */
declare function rehypeInlineCodeProperty(): (tree: any) => undefined;
/**
 * Function to determine if code is inline based on the presence of line breaks
 *
 * @example
 * const isInline = node && isInlineCode(node: Element)
 */
declare const isInlineCode: (node: Element) => boolean;

/**
 * Props for the ShikiHighlighter component
 */
interface ShikiHighlighterProps extends HighlighterOptions {
    /**
     * The programming language for syntax highlighting
     * Supports custom textmate grammar objects in addition to Shiki's bundled languages
     * @see https://shiki.style/languages
     */
    language: Language;
    /**
     * The code to be highlighted
     */
    children: string;
    /**
     * The color theme or themes for syntax highlighting
     * Supports single, dual, or multiple themes
     * Supports custom textmate theme objects in addition to Shiki's bundled themes
     *
     * @example
     * theme='github-dark' // single theme
     * theme={{ light: 'github-light', dark: 'github-dark' }} // multi-theme
     *
     * @see https://shiki.style/themes
     */
    theme: Theme | Themes;
    /**
     * Controls the application of default styles to the generated code blocks
     *
     * Default styles include padding, overflow handling, border radius, language label styling, and font settings
     * @default true
     */
    addDefaultStyles?: boolean;
    /**
     * Add custom inline styles to the generated code block
     */
    style?: React.CSSProperties;
    /**
     * Add custom inline styles to the language label
     */
    langStyle?: React.CSSProperties;
    /**
     * Add custom CSS class names to the generated code block
     */
    className?: string;
    /**
     * Add custom CSS class names to the language label
     */
    langClassName?: string;
    /**
     * Whether to show the language label
     * @default true
     */
    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'
     */
    as?: React.ElementType;
}

export { type Element as E, type HighlighterOptions as H, type Language as L, type ShikiHighlighterProps as S, type Theme as T, type UseShikiHighlighter as U, type Themes as a, isInlineCode as i, rehypeInlineCodeProperty as r };