> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Basic Usage

There are two ways to use the library: the source component for direct rendering, and the explicit pipeline that separates parsing, preparation, and rendering for servers, caches, workers, and async work. See [How it works](/guide/concepts.md) for how the outputs and entries relate.

## Source component

```tsx
import { Wikitext } from "react-wikitext";
import "react-wikitext/styles.css";

export function Article({ source }: { source: string }) {
  return (
    <Wikitext
      source={source}
      parseOptions={{ pageName: "Example" }}
      prepareOptions={{ headingIdStrategy: "instance" }}
      lang="en"
    />
  );
}
```

`Wikitext` performs the following synchronously:

1. Parses the source with `parseWikitext` or the supplied `parser`.
2. Clones the semantic tree, runs plugins, generates HAST, and sanitizes it with `prepareWikitext`.
3. Renders with `WikitextView`.

It memoizes parsing and preparation with `[parser, source, parseOptions]` and `[document, prepareOptions]`. Inline option objects cause a reparse on every render; keep options stable or wrap them in `useMemo`.

:::warning
The root entry only uses the synchronous prepare path. Async plugins in `wikitextPlugins` / `rehypePlugins` make `Wikitext` throw `ASYNC_PLUGIN_IN_SYNC_PATH`. Use the explicit pipeline for async plugins.
:::

## Explicit pipeline

```tsx
import { createWikiparser } from "react-wikitext/parse";
import { prepareWikitext } from "react-wikitext/hast";
import { WikitextView } from "react-wikitext/view";
import "react-wikitext/styles.css";

const parser = createWikiparser();

export function renderArticle(source: string) {
  const document = parser.parse(source, { pageName: "Example" });
  const prepared = prepareWikitext(document, {
    headingIdStrategy: "instance",
  });
  return <WikitextView document={prepared} lang="en" />;
}
```

Parsing and preparation can happen outside React. `prepareWikitext` does not modify the original parse snapshot; plugins run on a cloned semantic tree.

Create the parser once at module scope and reuse it. Its config is fixed at creation; changing site config requires a new parser:

```ts
import { createWikiparser } from "react-wikitext/parse";
import { MEDIAWIKI_CONFIG } from "react-wikitext/configs";

export const parser = createWikiparser({
  config: MEDIAWIKI_CONFIG,
  defaults: { pageName: "Example" },
});
```

## Reusing prepared output

Preparation reruns plugins, HAST conversion, and sanitization. When only presentation components change, reuse the existing render snapshot:

```tsx
import type { WikitextRenderDocument } from "react-wikitext/hast";
import { WikitextView } from "react-wikitext/view";

function Article({ prepared }: { prepared: WikitextRenderDocument }) {
  return (
    <WikitextView
      document={prepared}
      semanticComponents={{
        template: ({ displayName }) => <span className="template-chip">{displayName}</span>,
      }}
    />
  );
}
```

- A parse cache key should include the source, `pageName`, and site config.
- A render cache key also includes resolvers, plugins, `policy`, `labels`, and `headingIdStrategy`.
- Caching and invalidation are covered in [Performance and budgets](/guide/performance.md).

## Async plugins

The synchronous entry rejects async plugins. Use `prepareWikitextAsync` when a transformation is asynchronous:

```tsx
import { prepareWikitextAsync } from "react-wikitext/hast";

const prepared = await prepareWikitextAsync(document, {
  rehypePlugins: [
    () => async (tree) => {
      // Fetch data or rewrite HAST asynchronously
      return tree;
    },
  ],
});
```

Preparation must finish before React renders; `WikitextView` never waits for a Promise. For server scenarios, see [Server rendering](/guide/server-rendering.md).

## Component overrides

`Wikitext` and `WikitextView` accept `components` (by HTML tag) and `semanticComponents` (by wiki semantic type). Overrides are trusted code and are the right place to integrate a design system:

```tsx preview
import type { ReactNode } from "react";
import { Wikitext } from "react-wikitext";
import "react-wikitext/styles.css";

const source = `<blockquote>This quote uses a custom component.</blockquote>

{{Infobox|title=Template badge}}`;

function Quote({ children }: { children?: ReactNode }) {
  return (
    <blockquote style={{ borderLeft: "3px solid #0969da", margin: "8px 0", paddingLeft: 12 }}>
      {children}
    </blockquote>
  );
}

export default function Demo() {
  return (
    <Wikitext
      source={source}
      lang="en"
      components={{ blockquote: Quote }}
      semanticComponents={{
        template: ({ displayName }) => (
          <span style={{ background: "#ddf4ff", borderRadius: 999, padding: "2px 8px" }}>
            {displayName}
          </span>
        ),
      }}
    />
  );
}
```

See the [React component API](/api/react.md) for the full mapping and props; styling, labels, and heading anchors are in [Styling and components](/guide/customization.md).

## Working with AI

This docs site is built with `llms` support: besides the copy-Markdown and open-in-ChatGPT/Claude entries under each page title, two plain-text files for LLMs are published alongside the site on every build:

- [llms.txt](https://react-wikitext.pages.dev/llms.txt): an index file with descriptions and links for every page on the site
  ```
  https://react-wikitext.pages.dev/llms.txt
  ```
- [llms-full.txt](https://react-wikitext.pages.dev/llms-full.txt): the entire English site content merged into one file
  ```
  https://react-wikitext.pages.dev/llms-full.txt
  ```

The Chinese site publishes the same files under `/zh/`: `/zh/llms.txt` and `/zh/llms-full.txt`. When citing a single page, appending `.md` to its URL also gives you the plain-Markdown version of that page.

Copy whichever link fits your use case and hand it to your agent.

## Related

- [Server rendering](/guide/server-rendering.md): server preparation, serialization, Next.js, and hydration.
- [Performance and budgets](/guide/performance.md): budgets, workers, and caching.
- [Troubleshooting](/guide/troubleshooting.md): `ASYNC_PLUGIN_IN_SYNC_PATH` and other common errors.