onMounted

onMounted(fn) registers work that only makes sense in the browser with the DOM ready: measuring an element, focusing a field, subscribing to window, starting a library. fn runs once when component hydration or mounting finishes, with bindings and ref: values already assigned. It never runs on the server, so code inside can use window and document without checking.

If fn returns a function, Meeko registers it as component cleanup, like onCleanup. It is exported from @meekojs/meeko and auto-imported in framework applications.

Usage#

<!-- app/components/WindowWidth.meeko -->
<script lang="ts">
const width = signal(0);
onMounted(() => {
  const update = (): void => { width.value = window.innerWidth; };
  update();
  window.addEventListener("resize", update);
  return () => window.removeEventListener("resize", update);
});
</script>

<template><p>{width.value}px</p></template>

Server HTML displays 0px; on hydration, onMounted measures the window and the template updates. When the component unmounts, the returned function removes the listener.

Type#

function onMounted(fn: () => MountedResult): void

type ErrorSource =
  | "event"
  | "effect"
  | "cleanup"
  | "mounted"
  | "navigation"
  | "socket"
  | "uncaught"
  | "rejection"

Parameters#

Return value#

void. Throws Error: onMounted() must be called while a component script runs if called outside a component script, and TypeError: onMounted() expects a function if fn is not a function.

Examples#

Focus a field when it appears#

<script lang="ts">
const field = useElementRef("search");
onMounted(() => field.value?.focus());
</script>

<template><input ref:search type="search" placeholder="Search"></template>

A library that needs the element#

<!-- app/components/Map.meeko -->
<script lang="ts">
import { createMap } from "../lib/map";

const props = defineProps<{ lat: number; lng: number }>();
const container = useElementRef("map");
onMounted(() => {
  const map = createMap(container.value!, { center: [props.lat, props.lng] });
  effect(() => map.setCenter([props.lat, props.lng]));
  return () => map.destroy();
});
</script>

<template><div ref:map class="map"></div></template>

The effect created inside tracks props and stops with the component.

Asynchronous work with its own cleanup#

An async function cannot return cleanup: register it with onCleanup before the first await.

<script lang="ts">
const stats = signal<{ visits: number } | null>(null);
onMounted(async () => {
  const controller = new AbortController();
  onCleanup(() => controller.abort());
  const response = await fetch("/api/stats", { signal: controller.signal });
  stats.value = (await response.json()) as { visits: number };
});
</script>

<template><p if:when="stats.value">{stats.value.visits} visits</p></template>

If the request fails, the error reaches the error observer with source "mounted".

Parent and child ordering#

Within the same hydration or mount operation, children run their onMounted before the parent, and multiple callbacks in a component run in registration order. A child can therefore emit an event in its onMounted and the parent's bindings are already ready to receive it.

Common mistakes#

Return cleanup from an async function#

onMounted(async () => {
  const id = setInterval(tick, 1000);
  return () => clearInterval(id);
});

meeko check reports TS2345: Argument of type '() => Promise<() => void>' is not assignable to parameter of type '() => MountedResult': cleanup would arrive inside a promise and Meeko would not run it. Use onCleanup before the first await, or a synchronous function:

onMounted(() => {
  const id = setInterval(tick, 1000);
  return () => clearInterval(id);
});

Call it outside setup#

async function open(): Promise<void> {
  await loadPanel();
  onMounted(() => panel.value?.focus());
}

At runtime it throws Error: onMounted() must be called while a component script runs. Call it at the script's top level, or do the work directly in the handler, where the component is already mounted:

async function open(): Promise<void> {
  await loadPanel();
  panel.value?.focus();
}

Use it in <script server>#

onMounted belongs to the component, which runs in the browser; a page's server block is not mounted.

<script server lang="ts">
onMounted(() => console.log("listo"));
</script>

meeko check reports MEEK108: onMounted() sólo existe en el <script> de un componente: <script server> se ejecuta fuera del componente, antes de renderizar la página. Muévelo al <script lang="ts">.

<script lang="ts">
onMounted(() => console.log("listo"));
</script>

Notes#

• SSR. Never runs on the server or in an HTML-only render: a navigation's dry run or the render before mounting a region in the browser.
• Timing. At the end of the current hydration or mount operation, once everything that operation created exists: the component, its later siblings and its parent's bindings. A component appearing later (a satisfied if:when, a new each:of row, a navigation's page) follows the same rule in its own mount operation.
• Restored values. useStorage, useTheme and controls with model edited by the user before hydration apply their values just before onMounted callbacks, so the callback already sees them.
• No tracking. Callbacks run without subscribing to signals they read: reading count.value inside does not repeat them. To react to changes, create an effect.
• Errors. A synchronous failure or rejected promise reaches the nearest provideErrorHandler (or the application's onError) with source "mounted"; it does not stop other callbacks or undo hydration. If hydration fails, or the component is disposed of before mounting finishes, its callbacks do not run.
• After a browser await. In the continuation of await useElementRef(...) or await useSocket(...), the component is already mounted, and onMounted runs the callback immediately.

Related#

• onCleanupRegisters synchronous resource cleanup in the active root, executed when the component unmounts or is disposed of.
• effectRuns a synchronous function now and whenever a signal it read changes; returns the function that stops it.
• useElementRefReads the template element or component named with ref: from the script, as a signal or, with await, already mounted.
• provideErrorHandlerRegisters the browser failure observer for a component and its entire branch, with each failure's source.
• LifecycleMeeko API
• Top-level composables and awaitMeeko API