CodeBlock

Server Only

Renders a pre element with syntax highlighting, type information, and type checking.

This component is automatically set up to override the pre element when using the Next.js plugin.

Styling

The CodeBlock component can be styled using the className and style props to target specific descendant elements.

import { CodeBlock as MdxtsCodeBlock, Tokens } from 'mdxts/components'
import styles from './CodeBlock.module.css'

export function CodeBlock(props: React.ComponentProps<typeof MdxtsCodeBlock>) {
  return (
    <CodeBlock
      source="./counter/useCounter.ts"
      className={{
        container: styles.container,
        token: styles.token,
      }}
      style={{
        // Clear the default styles
        container: {
          boxShadow: undefined,
          borderRadius: undefined,
        },
      }}
    />
  )
}

Not every element can be styled using the className and style props. See the following section for fully customizing the CodeBlock component.

Overrides

If you need more customization, the CodeBlock component can be fully overridden by importing it from mdxts/components and extending it:

CodeBlock.tsx

import { CodeBlock as MdxtsCodeBlock, Tokens } from 'mdxts/components'

export function CodeBlock(props: React.ComponentProps<typeof MdxtsCodeBlock>) {
  return (
    <MdxtsCodeBlock {...props}>
      <Tokens />
    </MdxtsCodeBlock>
  )
}

This will only render highlighted tokens. Use the other CodeBlock components like LineNumbers and Toolbar to render the other parts of the code block.

Now import the CodeBlock component in your mdx-components.tsx file and override the pre component to use it instead of the default CodeBlock component:

mdx-components.tsx

import { MDXComponents } from 'mdxts/components'
import { CodeBlock } from './CodeBlock'

export function useMDXComponents() {
  return {
    ...MDXComponents,
    pre: CodeBlock,
  } satisfies MDXComponents
}

Examples

./counter/useCounter.ts

import { useState } from 'react'

export function useCounter(initialValue: number = 0) {
  const [count, setCount] = useState(initialValue)
  return {
    count,
    increment: () => setCount(count + 1),
    decrement: () => setCount(count - 1),
  }
}

Basic

const a = 1
a + b

Type Checking

example.ts

const a = 1

example.ts

const a = 1
const b = 2

Ordered

line-numbers.ts

1
2
3
4
5
const a = 1
const b = 2

const add = a + b
const subtract = a - b

Line Numbering

line-highlight.ts

const a = 1
const b = 2

const add = a + b
const subtract = a - b

Line Highlighting

line-focus.ts

const a = 1
const b = 2

const add = a + b
const subtract = a - b

Line Focusing

line-highlight-and-focus.ts

const a = 1
const b = 2

const add = a + b
const subtract = a - b

Line Highlight and Focus

toolbar.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
'use client'
import React from 'react'
import { useCounter } from './useCounter'

export default function Counter({ initialCount }: { initialCount: number }) {
  const { count, decrement, increment } = useCounter(initialCount)
  return (
    <div>
      <button onClick={decrement}>-</button>
      <span>{count}</span>
      <button onClick={increment}>+</button>
    </div>
  )
}

Custom

API Reference

CodeBlock

View Source

CodeBlockProps

Union

value *

string

Source code to highlight.

source *

string

Path to the source file on disk to highlight.

workingDirectory

string

The working directory for the source. Added automatically when using mdxts/loader.

filename

string

Name or path of the code block. Ordered filenames will be stripped from the name e.g. 01.index.tsx becomes index.tsx.

language

Languages

Language of the source code. When used with source, the file extension will be used by default.

highlightedLines

string

A string of comma separated lines and ranges to highlight e.g. '1, 3-5, 7'.

focusedLines

string

A string of comma separated lines and ranges to focus e.g. '6-8, 12'.

unfocusedLinesOpacity

number= 0.6

Opacity of unfocused lines when using focusedLines.

allowCopy

boolean

Show or hide a button that copies the source code to the clipboard.

allowErrors

boolean | string

Whether or not to allow errors. Accepts a boolean or comma-separated list of allowed error codes.

showErrors

boolean

Show or hide error diagnostics.

showLineNumbers

boolean

Show or hide line numbers.

showToolbar

boolean

Show or hide the toolbar.

sourcePath

string | false

Path to the source file on disk in development and the git provider source in production.

fixImports

boolean

Whether or not to attempt to fix broken imports. Useful for code using imports outside of the project.

className

{ container?: string toolbar?: string lineNumbers?: string token?: string popover?: string }

Class names to apply to code block elements. Use the children prop for full control of styling.

container

string

toolbar

string

lineNumbers

string

token

string

popover

string

style

{ container?: React.CSSProperties toolbar?: React.CSSProperties lineNumbers?: React.CSSProperties token?: React.CSSProperties popover?: React.CSSProperties }

Styles to apply to code block elements. Use the children prop for full control of styling.

container

React.CSSProperties

toolbar

React.CSSProperties

lineNumbers

React.CSSProperties

token

React.CSSProperties

popover

React.CSSProperties

children

React.ReactNode

Overrides default rendering to allow full control over styles using CodeBlock components like Tokens, LineNumbers, and Toolbar.

Last updated 05/12/24