#React Components

Both the root entry and /view export the view components; only the root entry exports the Wikitext source component.

#Wikitext

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

<Wikitext source={source} lang="en" />;

The source component parses, prepares, and renders in one step. It only supports the synchronous pipeline.

#Props

interface WikitextProps extends Omit<WikitextViewProps, "document"> {
  source: string;
  parser?: WikitextParser;
  parseOptions?: WikitextParseOptions;
  prepareOptions?: WikitextPrepareOptions;
  onError?: (error: Error, info: { stage: "parse" | "prepare" }) => void;
  fallback?:
    React.ReactNode | ((error: Error, info: { stage: "parse" | "prepare" }) => React.ReactNode);
}

#Behavior

• Parsing and preparation are memoized with [parser, source, parseOptions] and [document, prepareOptions].
• New option objects on every render cause reparsing; keep references stable.
• Plugins and resolvers must be pure; an async plugin throws ASYNC_PLUGIN_IN_SYNC_PATH.
• The default parser initializes when the module loads; use /view when you do not need a parser.

#WikitextView

import { WikitextView } from "react-wikitext/view";

<WikitextView document={prepared} lang="en" />;

WikitextView accepts only a prepared render snapshot. It never parses source, runs plugins, or calls resolvers during rendering.

#Props

• The root is always div.wtr-view.
• idPrefix affects heading ids, in-document #fragment links, and table headers.
• Each top-level block is wrapped in an error boundary; one failing block does not affect others.
• The view builds semantic and HAST indexes for components and WikitextFragment.

#WikitextFragment

import { WikitextFragment } from "react-wikitext/view";

<WikitextFragment nodes={node.children} mode="block" />;

• Must be used inside the <WikitextView> context, otherwise it throws.
• nodes must be the same node objects from the current view document; matching ids are not enough.
• It renders only nodes found in the prepared HAST index, which suits template parameters, file captions, and ref content.
• Inline mode without className adds no wrapper; with className it uses <span>. Block mode uses a wtr-fragment container.
• Rendering the same node twice in one view duplicates content and heading ids.

#Component overrides

#HTML components

type WikitextHtmlComponents = Partial<
  Record<string, React.ComponentType<WikitextHtmlComponentProps>>
>;

interface WikitextHtmlComponentProps extends React.HTMLAttributes<HTMLElement> {
  node?: import("hast").Element;
  document: WikitextRenderDocument;
  semantic?: WikitextNode;
  origin?: WikitextOrigin;
  children?: React.ReactNode;
  href?: string;
  src?: string;
  alt?: string;
}

Mapped by tag name, such as p, table, img, or a. Components receive sanitized DOM props plus the HAST element, document, and optional semantic node.

#Semantic components

type WikitextSemanticComponents = {
  link?: React.ComponentType<WikitextLinkComponentProps>;
  template?: React.ComponentType<WikitextTemplateComponentProps>;
  parserFunction?: React.ComponentType<WikitextTemplateComponentProps>;
  argument?: React.ComponentType<WikitextSemanticComponentProps<WikitextArgument>>;
  file?: React.ComponentType<WikitextFileComponentProps>;
  reference?: React.ComponentType<WikitextReferenceComponentProps>;
  extension?: React.ComponentType<WikitextExtensionComponentProps>;
  unknown?: React.ComponentType<WikitextUnknownComponentProps>;
  table?: React.ComponentType<WikitextSemanticComponentProps<WikitextTable>>;
};

Every semantic component receives:

interface WikitextSemanticComponentProps<Node extends WikitextNode> {
  document: WikitextRenderDocument;
  node: Node;
  hastNode: import("hast").Element;
  origin?: WikitextOrigin;
  children?: React.ReactNode;
}

Extra props:

Precedence: an explicit semantic component replaces the entire semantic structure; otherwise tags inside the default HAST structure use components; otherwise native elements are used.

#Custom template card

import { WikitextFragment, type WikitextTemplateComponentProps } from "react-wikitext/view";

function TemplateCard({ displayName, node }: WikitextTemplateComponentProps) {
  return (
    <aside className="template-card">
      <strong>{displayName}</strong>
      <WikitextFragment nodes={node.children} mode="block" />
    </aside>
  );
}

<WikitextView document={prepared} semanticComponents={{ template: TemplateCard }} />;

#Custom link

<WikitextView
  document={prepared}
  semanticComponents={{
    link: ({ href, external, children }) =>
      href ? (
        <a
          href={href}
          {...(external ? { target: "_blank", rel: "nofollow noopener noreferrer" } : {})}
        >
          {children}
        </a>
      ) : (
        <span className="unresolved-link">{children}</span>
      ),
  }}
/>

#Context hooks

interface WikitextViewContextValue {
  document: WikitextRenderDocument;
  semanticIndex: ReadonlyMap<string, WikitextNode>;
  hastIndex: ReadonlyMap<string, import("hast").ElementContent>;
  components: WikitextHtmlComponents;
  semanticComponents: WikitextSemanticComponents;
  idPrefix: string;
  mapId: (id: string) => string;
  mapHref: (href: string) => string;
  onRenderError?: (error: Error, info: { node: WikitextNode }) => void;
}

function useWikitextContext(): WikitextViewContextValue;
function useWikitextLabels(): WikitextLabels;
function useWikitextIds(): { toDomId(id: string): string; toHref(href: string): string };

• These hooks must be used inside <WikitextView>.
• useWikitextLabels() reads the final labels from the render snapshot.
• useWikitextIds() suits custom components that need to generate anchors or fragment links.

#Render errors

<Wikitext
  source={source}
  onRenderError={(error, { node }) => {
    reportError(error, { nodeType: node.type, nodeId: node.id });
  }}
/>

Error boundaries isolate top-level HAST blocks. The placeholder shows labels.renderFailed, the node type, and the source. Parse and prepare errors do not enter this boundary and should be caught by the caller.

#Related types

The root entry additionally exports selected semantic types used by view props: WikitextLink, WikitextTemplate, WikitextFile, WikitextReference, WikitextTable, WikitextUnknown, and more. Import the full node subtypes and AST tools from /ast.