#Links and Images

The library does not decode site routes or load images by default. Links and media addresses are decided by the host; the library validates, sanitizes, and renders them.

#Links

#Default behavior

External links allow only http:, https:, and mailto:; addresses that cannot be parsed safely degrade to blocked, readable text. Absolute HTTP(S) / mailto links default to target="_blank" and rel="nofollow noopener noreferrer".

#resolveLink

import type { WikitextLinkResolver } from "react-wikitext/hast";

const resolveLink: WikitextLinkResolver = (request) => {
  if (request.kind === "internal") {
    const page = request.page ?? request.target.replace(/^:/u, "");
    return {
      href: `/wiki/${encodeURIComponent(page)}${request.fragment ? `#${request.fragment}` : ""}`,
      target: "_self",
    };
  }
  return undefined;
};

Return values:

request provides kind and target; internal links may also have page and fragment. context provides the original parse snapshot document, the current working tree ast, and the current node.

The example below gives internal links a site path while external links keep the default handling:

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

export default function Demo() {
  return (
    <Wikitext
      source="See [[Wikitext|this library]] and the [https://example.com example site]."
      lang="en"
      prepareOptions={{
        resolveLink: (request) =>
          request.kind === "internal" ? { href: "/guide/quick-start", target: "_self" } : undefined,
      }}
    />
  );
}

#External link policy

• policy.allowRelativeLinks defaults to true, allowing resolver-returned relative addresses.
• policy.externalLinkTarget defaults to "_blank"; set it to null to omit target.
• Relative links opened with _blank gain noopener noreferrer; finalization removes invalid targets and unknown rel tokens.

#Images

#Default behavior

File nodes render as placeholders with captions. Without resolveImage, the library never produces <img> and never requests an image URL.

#resolveImage

import type { WikitextImageResolver } from "react-wikitext/hast";

const resolveImage: WikitextImageResolver = (request) => ({
  src: `https://cdn.example.com/wiki/${encodeURIComponent(request.name)}`,
  alt: request.alt ?? request.name,
  ...(request.width === undefined ? {} : { width: request.width }),
  ...(request.height === undefined ? {} : { height: request.height }),
});

• Returning null keeps the placeholder; returning an object authorizes the resource.
• src allows only http: / https:; enable policy.allowRelativeImages for relative images.
• request provides name, parameters, parsed width / height, alt, and caption.
• Dimensions are clamped to 1–4096; resolver values take precedence.
• The generated <img> always has loading="lazy" and decoding="async"; alt falls back to the file name.

#Captions and links

• The caption prefers explicit caption=, otherwise the unnamed caption; links and template placeholders inside it render recursively.
• The file parameter link= is sanitized and produces a link; class= becomes an extra class.
• Inline files use <span>; block files use <figure>. Compatibility classes such as mw-default-size and mw-halign-* are preserved.

#Authorization and security

Preparation records the image addresses that a resolver actually returned and the library validated. During finalization:

• An unauthorized <img> is removed. Its alt text is preserved when present, and an UNAUTHORIZED_IMAGE diagnostic is recorded. Resolver output uses authorizedImages, source HTML uses policy.allowSourceImages, and plugin output uses policy.allowPluginImages.
• Plugins cannot bypass the default no-image policy by inserting arbitrary <img> elements.
• URLs are entity-decoded, stripped of control characters, and validated against the protocol whitelist before becoming attributes.

You can pre-process URLs with sanitizeHref, sanitizeImageUrl, and sanitizedAttributesToProps from /hast. The final stage validates again.

#Policy and components

To adjust defaults without a resolver:

<Wikitext
  source={source}
  prepareOptions={{
    policy: {
      externalLinkTarget: null,
    },
  }}
/>

policy is shallow-merged with defaults. extraTags and stripTags are replaced wholesale, not appended. Spread DEFAULT_PREPARE_POLICY when you want to keep the defaults.

Final link and file appearance can be taken over with HTML or semantic components. Custom components are trusted code; their output is not sanitized again.