# Prism React Renderer

Prism React Renderer is a React component library for syntax highlighting using Prism.js. It provides a render-props-driven approach to render syntax-highlighted code directly in React applications with VSCode-like theming capabilities.

## Package Information

- **Package Name**: prism-react-renderer
- **Package Type**: npm
- **Language**: TypeScript
- **Installation**: `npm install prism-react-renderer`
- **Peer Dependencies**: React >=16.0.0
- **Dependencies**: @types/prismjs, clsx

## Core Imports

```typescript
import { Highlight, themes, Prism } from "prism-react-renderer";
```

For CommonJS:

```javascript
const { Highlight, themes, Prism } = require("prism-react-renderer");
```

Additional imports for advanced usage:

```typescript
import { 
  useTokenize, 
  normalizeTokens,
  type PrismTheme,
  type Token,
  type RenderProps 
} from "prism-react-renderer";
```

## Basic Usage

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

function CodeBlock({ code, language }) {
  return (
    <Highlight
      theme={themes.vsDark}
      code={code}
      language={language}
    >
      {({ className, style, tokens, getLineProps, getTokenProps }) => (
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div key={i} {...getLineProps({ line })}>
              {line.map((token, key) => (
                <span key={key} {...getTokenProps({ token })} />
              ))}
            </div>
          ))}
        </pre>
      )}
    </Highlight>
  );
}
```

## Architecture

Prism React Renderer is built around several key components:

- **Highlight Component**: Main render-props component that orchestrates syntax highlighting
- **Bundled Prism Instance**: Modified Prism.js that doesn't pollute global namespace
- **Theme System**: VSCode-compatible themes with language-specific styling support
- **Tokenization Hooks**: React hooks for tokenizing code and generating element props
- **Utility Functions**: Functions for normalizing tokens and converting themes

## Capabilities

### Syntax Highlighting

Core syntax highlighting functionality using the render props pattern for maximum flexibility. Supports 20+ programming languages and provides complete control over rendering.

```typescript { .api }
interface HighlightProps {
  prism?: PrismLib;
  theme?: PrismTheme;
  language: Language;
  code: string;
  children: (props: RenderProps) => JSX.Element;
}

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

[Component and Hooks](./component-hooks.md)

### Built-in Themes

Collection of 20 built-in syntax highlighting themes inspired by popular code editors like VSCode, with support for language-specific styling.

```typescript { .api }
declare const themes: {
  dracula: PrismTheme;
  duotoneDark: PrismTheme;
  duotoneLight: PrismTheme;
  github: PrismTheme;
  nightOwl: PrismTheme;
  nightOwlLight: PrismTheme;
  oceanicNext: PrismTheme;
  okaidia: PrismTheme;
  palenight: PrismTheme;
  shadesOfPurple: PrismTheme;
  synthwave84: PrismTheme;
  ultramin: PrismTheme;
  vsDark: PrismTheme;
  vsLight: PrismTheme;
  jettwaveDark: PrismTheme;
  jettwaveLight: PrismTheme;
  oneDark: PrismTheme;
  oneLight: PrismTheme;
  gruvboxMaterialDark: PrismTheme;
  gruvboxMaterialLight: PrismTheme;
};
```

[Themes](./themes.md)

### Bundled Prism Instance

Pre-configured Prism.js instance with common programming languages bundled for optimal performance and no global namespace pollution.

```typescript { .api }
declare const Prism: PrismLib;

interface PrismLib {
  languages: Record<string, PrismGrammar>;
  tokenize(text: string, grammar: PrismGrammar): (string | PrismToken)[];
  hooks: {
    run(name: string, env: EnvConfig): void;
  };
}
```

**Supported Languages**: markup, jsx, tsx, swift, kotlin, objectivec, js-extras, reason, rust, graphql, yaml, go, cpp, markdown, python, json (and their dependencies)

[Utilities](./utilities.md)

## Core Types

```typescript { .api }
type Language = string;

interface Token {
  types: string[];
  content: string;
  empty?: boolean;
}

interface RenderProps {
  tokens: Token[][];
  className: string;
  style: CSSProperties;
  getLineProps: (input: LineInputProps) => LineOutputProps;
  getTokenProps: (input: TokenInputProps) => TokenOutputProps;
}

interface PrismTheme {
  plain: PrismThemeEntry;
  styles: Array<{
    types: string[];
    style: PrismThemeEntry;
    languages?: Language[];
  }>;
}

interface PrismThemeEntry {
  color?: string;
  background?: string;
  backgroundColor?: string;
  fontStyle?: "normal" | "italic";
  fontWeight?: "normal" | "bold" | "100" | "200" | "300" | "400" | "500" | "600" | "700" | "800" | "900";
  textDecorationLine?: "none" | "underline" | "line-through" | "underline line-through";
  opacity?: number;
  cursor?: string;
  textShadow?: string;
  backgroundImage?: string;
}

interface LineInputProps {
  style?: CSSProperties;
  className?: string;
  line: Token[];
  [key: string]: unknown;
}

interface LineOutputProps {
  style?: CSSProperties;
  className: string;
  [key: string]: unknown;
}

interface TokenInputProps {
  style?: CSSProperties;
  className?: string;
  token: Token;
  [key: string]: unknown;
}

interface TokenOutputProps {
  style?: CSSProperties;
  className: string;
  children: string;
  [key: string]: unknown;
}

type PrismGrammar = import("prismjs").Grammar;
type PrismLib = typeof import("prismjs");
```