{"id":15292084,"url":"https://github.com/zhangyu1818/react-markdown-toc","last_synced_at":"2026-01-05T14:11:08.231Z","repository":{"id":233453320,"uuid":"786945646","full_name":"zhangyu1818/react-markdown-toc","owner":"zhangyu1818","description":"Generating a Table of Contents (TOC) from Markdown.","archived":false,"fork":false,"pushed_at":"2024-05-26T09:22:56.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-07-01T17:07:27.723Z","etag":null,"topics":["markdown-toc","react","react-markdown","react-markdown-toc","toc"],"latest_commit_sha":null,"homepage":"https://zhangyu1818.github.io/react-markdown-toc/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhangyu1818.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-15T15:45:32.000Z","updated_at":"2024-05-26T09:22:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"c31950c5-78d7-4e6b-8f17-d96509f2334b","html_url":"https://github.com/zhangyu1818/react-markdown-toc","commit_stats":null,"previous_names":["zhangyu1818/react-markdown-toc"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhangyu1818%2Freact-markdown-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhangyu1818%2Freact-markdown-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhangyu1818%2Freact-markdown-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhangyu1818%2Freact-markdown-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhangyu1818","download_url":"https://codeload.github.com/zhangyu1818/react-markdown-toc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245084610,"owners_count":20558248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown-toc","react","react-markdown","react-markdown-toc","toc"],"created_at":"2024-09-30T16:16:27.659Z","updated_at":"2026-01-05T14:11:08.189Z","avatar_url":"https://github.com/zhangyu1818.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-markdown-toc\n\n`react-markdown-toc` is a library designed for React applications, focused on generating a Table of Contents (TOC) from Markdown text.\n\n[Preview Link](https://zhangyu1818.github.io/react-markdown-toc/)\n\n## Features\n\n- **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.\n- **Fully Customizable**: Supports a wide range of customization options, including list style and link behavior, suitable for various design needs.\n- **Server and Client Side Support**: Compatible with React server components and client components, enabling it to adapt to different rendering strategies.\n\n## Installation\n\nYou can install `react-markdown-toc` using the following commands:\n\n```bash\nnpm install react-markdown-toc\n```\n\n## Usage\n\n### fromMarkdown\n\nThe `fromMarkdown` function is used to generate a TOC tree from a Markdown text.\n\n**Example Usage:**\n\n```js\nimport { fromMarkdown } from 'react-markdown-toc'\n\nconst [result, map] = fromMarkdown(`## Heading 1\\n\\n### Heading 1.1\\n\\n## Heading 2`)\n```\n\nThe `fromMarkdown` function returns a tuple containing the TOC tree and a map linking IDs to keys within the tree.\n\n### Server Component\n\nThe server component does not support custom rendering functions; it renders the ul, li, and a tags in a fixed manner.\n\n**Example Usage:**\n\n```jsx\nimport fs from 'node:fs/promises'\nimport { TOC } from 'react-markdown-toc/server'\n\nasync function App() {\n  const markdown = await fs.readFile('.example.md', 'utf-8')\n  return \u003cTOC markdown={markdown} className='ml-4' ul='pl-4' /\u003e\n}\n```\n\n#### Props\n\n- `markdown`: `string`, `required`\n  - The Markdown text to generate the TOC from.\n- `className`: `string`, `optional`\n  - Adds a custom class name to the outermost `\u003cul\u003e` for style customization.\n- `scrollAlign`: `start`|`center`|`end`, `optional`, default: `center`\n  - Determines which TOC item is considered active based on the scroll position, especially useful when multiple headings are visible in the viewport simultaneously.\n  - The options are `start` (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).\n- `throttleTime`: `number`, `optional`, default: `1000`\n  - Controls the throttling time for the scroll event to improve performance.\n\n### Client Component\n\nThe client component allows full customization of rendering, including the functions for rendering the `list`, `list items`, and `links`.\n\n**Example Usage:**\n\nUse `shadcn/ui` to implement a collapsible TOC list.\n\n[Preview Link](https://zhangyu1818.github.io/react-markdown-toc/)\n\n```jsx\nimport { useRouter } from 'next/navigation'\nimport { fromMarkdown } from 'react-markdown-toc'\nimport { TOC } from 'react-markdown-toc/client'\nimport { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@/components/ui/collapsible'\n\nfunction CustomTOC({ markdownString }) {\n  const router = useRouter()\n  const toc = fromMarkdown(markdownString)\n  return (\n    \u003cTOC\n      toc={toc}\n      scrollAlign='start'\n      renderList={children =\u003e (\n        \u003cCollapsibleContent className='pl-4 overflow-hidden data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up'\u003e\n          {children}\n        \u003c/CollapsibleContent\u003e\n      )}\n      renderListItem={(children, open) =\u003e \u003cCollapsible open={open}\u003e{children}\u003c/Collapsible\u003e}\n      renderLink={(children, href, active) =\u003e (\n        \u003cCollapsibleTrigger\u003e\n          \u003cspan\n            data-active={active}\n            role='button'\n            onClick={() =\u003e {\n              router.push(href, { scroll: false })\n              const target = document.querySelector(href)\n              target?.scrollIntoView({ behavior: 'smooth' })\n            }}\n          \u003e\n            {children}\n          \u003c/span\u003e\n        \u003c/CollapsibleTrigger\u003e\n      )}\n    /\u003e\n  )\n}\n```\n\n#### Props\n\n- `toc`: `readonly [Result, Map\u003cstring, string\u003e]`, `required`\n  - Obtained through the `fromMarkdown` method. This tuple contains the TOC tree and a map linking IDs to keys within the tree.\n- `scrollAlign`: `start`|`center`|`end`, `optional`, default: `center`\n  - Determines which TOC item is considered active based on the scroll position, especially useful when multiple headings are visible in the viewport simultaneously.\n  - The options are `start` (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).\n- `throttleTime`: `number`, `optional`, default: `1000`\n  - Controls the throttling time for the scroll event to improve performance.\n- `renderList`: `(children: React.ReactNode, active: boolean) =\u003e React.ReactNode`, `required`\n  - A custom rendering function for the list component, providing full control over the list's appearance and behavior.\n- `renderListItem`: `(children: React.ReactNode, active: boolean) =\u003e React.ReactNode`, `required`\n  - A custom rendering function for each list item, allowing for individual customization of list items within the TOC.\n- `renderLink`: `(children: React.ReactNode, url: string, active: boolean) =\u003e React.ReactNode`, `required`\n  - A custom function for rendering links, where you can specify the content, the target URL, and the active state styling or behavior.\n\n## Contribution\n\nContributions are always welcome!\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhangyu1818%2Freact-markdown-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhangyu1818%2Freact-markdown-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhangyu1818%2Freact-markdown-toc/lists"}