IncludeMarkup

IncludeMarkup dynamically fetches XMLUI markup from a URL and renders it inline. Use it to share common fragments (headers, footers, navigation bars, etc.) across multiple XMLUI apps without duplicating markup.

Key features:

• Dynamic inclusion: Fetch and render XMLUI markup from any URL at runtime
• Transparent rendering: The included content appears inline without injecting wrapper elements
• Loading placeholder: Show a spinner or message while the request is in-flight using loadingContent
• Reactive URL: Automatically re-fetches when the url prop changes
• Error handling: React to fetch failures and parse errors via didFail

How it works

IncludeMarkup fetches the XMLUI markup at the given URL and renders it as if it were part of the current document. The fetched content can be a <Fragment> with multiple children or a named <Component> definition — in the latter case the component wrapper is unwrapped automatically so only its children are inserted.

<Fragment>
  <Link to="https://docs.xmlui.org" label="Docs" />
  <Link to="https://blog.xmlui.org" label="Blog" />
</Fragment>

The URL is re-evaluated reactively. If the value of url changes, the component fetches the new resource and re-renders. The previous content is removed immediately as the new request starts.

CORS

When the app and the markup are served from different origins the server hosting the markup must include the appropriate Access-Control-Allow-Origin header. Browser same-origin policy is enforced as normal; IncludeMarkup has no way to bypass it.

Script sections

Only declarative XMLUI markup is supported. Any <script> section in the fetched file is silently ignored by the parser.

Shared navigation across a fleet of apps

A common reason to use IncludeMarkup is maintaining a single master copy of a navigation bar or footer and sharing it between several independent XMLUI deployments. Host the shared file on a CORS-enabled static server and include it in each app:

<App>
  <Pages>
    <Page url="/">
      <Text>Home page content</Text>
    </Page>
  </Pages>
  <Footer>
    <IncludeMarkup url="/markup/shared-footer.xmlui">
      <property name="loadingContent">
        <Text>Loading footer…</Text>
      </property>
    </IncludeMarkup>
  </Footer>
</App>

<App>
  <Pages>
    <Page url="/">
      <Text>Home page content</Text>
    </Page>
  </Pages>
  <Footer>
    <IncludeMarkup url="/markup/shared-footer.xmlui">
      <property name="loadingContent">
        <Text>Loading footer…</Text>
      </property>
    </IncludeMarkup>
  </Footer>
</App>

Conditional inclusion

Because url is a reactive expression you can include one of several fragments depending on runtime state:

<App var.role="user">
  <HStack marginBottom="0.5rem">
    <Button label="Switch to admin" onClick="role = 'admin'" />
    <Button label="Switch to user" onClick="role = 'user'" />
  </HStack>
  <IncludeMarkup url="{'/markup/' + role + '-nav.xmlui'}" />
</App>

<App var.role="user">
  <HStack marginBottom="0.5rem">
    <Button label="Switch to admin" onClick="role = 'admin'" />
    <Button label="Switch to user" onClick="role = 'user'" />
  </HStack>
  <IncludeMarkup url="{'/markup/' + role + '-nav.xmlui'}" />
</App>

Unwrapping a named Component

The fetched file can also be a full <Component> definition. IncludeMarkup automatically unwraps the component wrapper and renders its children inline:

<App>
  <IncludeMarkup url="/markup/footer-comp.xmlui" />
</App>

<App>
  <IncludeMarkup url="/markup/footer-comp.xmlui" />
</App>

Error boundary with fallback

Combine didFail with a var flag to display fallback content when the remote resource is down:

<App var.useFallback="{false}">
  <IncludeMarkup
    url="/markup/faulty-footer.xmlui"
    onDidFail="useFallback = true" />
  <Fragment when="{useFallback}">
    <ContentSeparator />
    <Text>© 2026 My Company</Text>
  </Fragment>
</App>

<App var.useFallback="{false}">
  <IncludeMarkup
    url="/markup/faulty-footer.xmlui"
    onDidFail="useFallback = true" />
  <Fragment when="{useFallback}">
    <ContentSeparator />
    <Text>© 2026 My Company</Text>
  </Fragment>
</App>

Behaviors

This component supports the following behaviors:

Properties

loadingContent

Optional content rendered while the request is in-flight. When the fetch completes this placeholder is replaced by the fetched markup.

Content displayed while the request is in-flight. Once the response arrives (successfully or with an error) this placeholder is replaced.

<App>
  <IncludeMarkup url="/markup/slow-header.xmlui">
    <property name="loadingContent">
      <HStack gap="0.5rem" verticalAlignment="center">
        <Spinner size="sm" />
        <Text>Loading…</Text>
      </HStack>
    </property>
  </IncludeMarkup>
</App>

<App>
  <IncludeMarkup url="/markup/slow-header.xmlui">
    <property name="loadingContent">
      <HStack gap="0.5rem" verticalAlignment="center">
        <Spinner size="sm" />
        <Text>Loading…</Text>
      </HStack>
    </property>
  </IncludeMarkup>
</App>

If loadingContent is not provided the component renders nothing until the fetch completes.

url

The URL to fetch XMLUI markup from. The component re-fetches and re-renders whenever this value changes. The server must allow cross-origin requests (CORS) when the app and the markup are served from different origins.

The component fetches and renders the markup at the specified URL. The URL is evaluated reactively — any change triggers a new fetch.

A binding expression is allowed, making it possible to swap the included content dynamically:

<App var.lang="en">
  <HStack>
    <Button label="English" onClick="lang = 'en'" />
    <Button label="German" onClick="lang = 'de'" />
  </HStack>
  <IncludeMarkup url="{'/markup/nav-' + lang + '.xmlui'}" />
</App>

<App var.lang="en">
  <HStack>
    <Button label="English" onClick="lang = 'en'" />
    <Button label="German" onClick="lang = 'de'" />
  </HStack>
  <IncludeMarkup url="{'/markup/nav-' + lang + '.xmlui'}" />
</App>

When url is empty or not set, the component renders nothing.

Events

didFail

This event fires when the fetch or parse operation fails (network error, non-2xx HTTP status, or XMLUI parse error).

Signature: didFail(message: string): void

• message: A human-readable description of the error that occurred.

Fires when the fetch or parse operation fails. The single message argument contains a human-readable description of the error (e.g. "HTTP 404 Not Found" or the text of a parse error).

<App var.error="">
  <IncludeMarkup
    url="/markup/missing.xmlui"
    onDidFail="msg => error = 'Load failed: ' + msg" />
  <Text when="{error}" value="{error}" color="$color-error" />
</App>

<App var.error="">
  <IncludeMarkup
    url="/markup/missing.xmlui"
    onDidFail="msg => error = 'Load failed: ' + msg" />
  <Text when="{error}" value="{error}" color="$color-error" />
</App>

Use didFail to render fallback content when the remote resource is unavailable:

<App var.failed="{false}">
  <IncludeMarkup
    url="/markup/failing-footer.xmlui"
    onDidFail="failed = true" />
  <HStack when="{failed}" gap="1rem">
    <Text>Docs</Text>
    <Text>Blog</Text>
    <Text>GitHub</Text>
  </HStack>
</App>

<App var.failed="{false}">
  <IncludeMarkup
    url="/markup/failing-footer.xmlui"
    onDidFail="failed = true" />
  <HStack when="{failed}" gap="1rem">
    <Text>Docs</Text>
    <Text>Blog</Text>
    <Text>GitHub</Text>
  </HStack>
</App>

didLoad

This event fires after the markup has been successfully fetched, parsed, and rendered.

Signature: didLoad(): void

Fires once after the markup has been successfully fetched, parsed, and rendered.

<App var.status="Fetching content…">
  <Text value="{status}" />
  <IncludeMarkup
    url="/markup/banner.xmlui"
    onDidLoad="status = 'Content loaded successfully ✓'" />
</App>

<App var.status="Fetching content…">
  <Text value="{status}" />
  <IncludeMarkup
    url="/markup/banner.xmlui"
    onDidLoad="status = 'Content loaded successfully ✓'" />
</App>

Exposed Methods

This component does not expose any methods.

Styling

This component does not have any styles.