react markdown toc
npm install react-markdown-tocreact-markdown-toc is a library designed for React applications, focused on generating a Table of Contents (TOC) from Markdown text.
- Fast and Accurate: Optimized for runtime performance, ensuring quick and accurate identification of the currently active section in the document. This feature is particularly beneficial for interactive documents where users might scroll frequently.
- Fully Customizable: Supports a wide range of customization options, including list style and link behavior, suitable for various design needs.
- Server and Client Side Support: Compatible with React server components and client components, enabling it to adapt to different rendering strategies.
You can install react-markdown-toc using the following commands:
``bash`
npm install react-markdown-toc
The fromMarkdown function is used to generate a TOC tree from a Markdown text.
Example Usage:
`js
import { fromMarkdown } from 'react-markdown-toc'
const [result, map] = fromMarkdown(## Heading 1\n\n### Heading 1.1\n\n## Heading 2)`
The fromMarkdown function returns a tuple containing the TOC tree and a map linking IDs to keys within the tree.
The server component does not support custom rendering functions; it renders the ul, li, and a tags in a fixed manner.
Example Usage:
`jsx
import fs from 'node:fs/promises'
import { TOC } from 'react-markdown-toc/server'
async function App() {
const markdown = await fs.readFile('.example.md', 'utf-8')
return
}
`
#### Props
- markdown: string, required
- The Markdown text to generate the TOC from.
- : string, optional
- Adds a custom class name to the outermost
for style customization.
- scrollAlign: start|center|end, optional, default: center
- Determines which TOC item is considered active based on the scroll position, especially useful when multiple headings are visible in the viewport simultaneously.
- The options are (the element closest to the top of the viewport), center (the element closest to the center of the viewport), and end (the element closest to the bottom of the viewport).
- throttleTime: number, optional, default: 1000
- Controls the throttling time for the scroll event to improve performance.$3
The client component allows full customization of rendering, including the functions for rendering the
, list items, and links.Example Usage:
Use
shadcn/ui to implement a collapsible TOC list.`jsx
import { useRouter } from 'next/navigation'
import { fromMarkdown } from 'react-markdown-toc'
import { TOC } from 'react-markdown-toc/client'
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@/components/ui/collapsible'function CustomTOC({ markdownString }) {
const router = useRouter()
const toc = fromMarkdown(markdownString)
return (
scrollAlign='start'
renderList={children => (
{children}
)}
renderListItem={(children, open) => {children} }
renderLink={(children, href, active) => (
role='button'
onClick={() => {
router.push(href, { scroll: false })
const target = document.querySelector(href)
target?.scrollIntoView({ behavior: 'smooth' })
}}
>
{children}
)}
/>
)
}
`#### Props
-
: readonly [Result, Map, required
- Obtained through the method. This tuple contains the TOC tree and a map linking IDs to keys within the tree.
- scrollAlign: start|center|end, optional, default: center
- Determines which TOC item is considered active based on the scroll position, especially useful when multiple headings are visible in the viewport simultaneously.
- The options are (the element closest to the top of the viewport), center (the element closest to the center of the viewport), and end (the element closest to the bottom of the viewport).
- throttleTime: number, optional, default: 1000
- Controls the throttling time for the scroll event to improve performance.
- : (children: React.ReactNode, active: boolean) => React.ReactNode, required
- A custom rendering function for the list component, providing full control over the list's appearance and behavior.
- : (children: React.ReactNode, active: boolean) => React.ReactNode, required
- A custom rendering function for each list item, allowing for individual customization of list items within the TOC.
- : (children: React.ReactNode, url: string, active: boolean) => React.ReactNode, required`Contributions are always welcome!