#Expansion /expand

import { expandWikitext, WikitextExpandError } from "react-wikitext/expand";

/expand expands supported templates and pure wikitext parser functions before parsing. It loads the parser but not React. Expansion is asynchronous.

#Signature

function expandWikitext(
  source: string,
  options: WikitextExpandOptions,
): Promise<WikitextExpandedDocument>;

interface WikitextExpandOptions {
  parser?: WikitextParser;
  pageName?: string;
  parseOptions?: Omit<WikitextParseOptions, "pageName">;
  resolveTemplate: WikitextTemplateResolver;
  maxDepth?: number;
  maxInvocations?: number;
  maxExpandedLength?: number;
  strict?: boolean;
  signal?: AbortSignal;
}

#Resolver

interface WikitextTemplateRequest {
  title: string;
  pageName?: string;
  callerTitle?: string;
  invocation: WikitextRange;
  signal?: AbortSignal;
}

type WikitextTemplateResolver = (
  request: WikitextTemplateRequest,
) => string | null | undefined | Promise<string | null | undefined>;

• null / undefined means the template is missing; an empty string is a valid template.
• A title is parsed once per expansion; the same title must return stable source.
• callerTitle is context only and does not participate in the cache key.
• invocation points at the top-level call range in original.source; nested requests reuse that range.
• The resolver performs remote fetching; the library makes no network requests.

#Result

interface WikitextExpandedDocument {
  original: WikitextDocument;
  document: WikitextDocument;
  expansion: WikitextExpansionInfo;
}

interface WikitextExpansionInfo {
  status: "complete" | "partial" | "fallback";
  records: readonly WikitextExpansionRecord[];
  diagnostics: readonly WikitextExpansionDiagnostic[];
}

interface WikitextExpansionRecord {
  kind: "template" | "parserFunction" | "argument";
  name: string;
  originalRange: WikitextRange;
  expandedRange: WikitextRange;
  status: "expanded" | "preserved";
}

• original is the parse snapshot of the original source.
• document is the parse snapshot of the expanded source and can be passed directly to prepareWikitext.
• status:
  • complete: all calls expanded.
  • partial: some calls were preserved or dependencies were unresolved.
  • fallback: the final source failed to parse, so the original snapshot was returned.
• expansion.diagnostics coordinates are based on original.source; document.diagnostics merges final parse diagnostics and mapped expansion diagnostics.

#What is expanded

Supported: template transclusion and parameters, include tags, #if, #ifeq, #switch, #iferror, {{!}}, {{=}}, and implicit newlines.

Preserved with diagnostics by default:

• #invoke and Lua.
• Transclusion modifiers such as subst.
• Functions that depend on site state or an external runtime, such as #ifexist and #time.

See the template expansion guide for details.

#Budgets and failures

• A single over-long call is preserved with LENGTH_BUDGET_EXCEEDED.
• If even the preserved source exceeds maxExpandedLength, the call throws EXPANSION_TOO_LARGE.
• With strict: true, a budget overrun throws EXPANSION_BUDGET_EXCEEDED.
• By default, a final parse failure returns the original valid snapshot with status: "fallback".
• Cancellation rejects with WikitextExpandError code ABORTED; the original reason is stored in cause.

parseOptions.maxSourceLength, template source length, and maxExpandedLength apply separately. Final parsing uses the effective maxExpandedLength.

#Errors

class WikitextExpandError extends WikitextError {
  readonly templateTitle?: string;
  readonly range?: WikitextRange;
  constructor(
    code: WikitextExpandErrorCode,
    message: string,
    options?: { cause?: unknown; templateTitle?: string; range?: WikitextRange },
  );
}

Common codes:

#With the view

import { expandWikitext } from "react-wikitext/expand";
import { prepareWikitext } from "react-wikitext/hast";
import { WikitextView } from "react-wikitext/view";

const expanded = await expandWikitext(source, { resolveTemplate });
const prepared = prepareWikitext(expanded.document);
const view = <WikitextView document={prepared} />;

The expanded document is already parsed; do not parse it again. Calls preserved after a failed expansion still render as template, function, or argument placeholders.