<MeekoAwait>

A useApi or useRpcQuery without await lets the component render immediately and requests data in the browser on mount. <MeekoAwait for="recurso"> wraps that data region and handles its states: the pending snippet on initial load, the error snippet (with a retry button) on failure, and its content when data exists. A refresh keeps content mounted. With reserve, while waiting it occupies the height it last had with data, so the page does not jump.

No import is needed: the compiler recognizes it, and a project component with the same name takes priority (MEEK106). Inside its content, meeko check and the editor read items.data.value as loaded.

Usage#

<!-- app/components/ItemsCard.meeko -->
<script lang="ts">
const items = useApi("/api/items");
</script>

<template>
  <section class="card">
    <h2>Items</h2>
    <MeekoAwait for="items" reserve>
      <snippet name="pending"><ItemsSkeleton /></snippet>
      <snippet name="error" params="error, retry"><p role="alert">Could not load. <button on:click="retry">Retry</button></p></snippet>
      <ItemsList bind:items="items.data.value" />
    </MeekoAwait>
  </section>
</template>

items.data.value is Item[] inside the tag, without ! or ?..

Type#

<MeekoAwait for="items" reserve>
  <snippet name="pending"><ItemsSkeleton /></snippet>
  <snippet name="error" params="error, retry">…</snippet>
  <ItemsList bind:items="items.data.value" />
</MeekoAwait>

interface MeekoAwaitProps {
	readonly for: AwaitResource | readonly AwaitResource[]
	readonly reserve?: boolean | string
	readonly messages?: AwaitMessages
	readonly class?: string
	readonly id?: string
}

type MeekoAwaitSnippets = {
	default: [refreshing: boolean]
	pending?: []
	error?: [error: Error, retry: () => void]
}

interface AwaitResource {
	readonly data: ReadonlySignal<unknown>
	readonly error: ReadonlySignal<Error | null>
	readonly pending: ReadonlySignal<boolean>
	refresh(): Promise<void>
}

Props#

Result#

An unstyled <div> that never changes its element, with:

• data-meeko-await="pending|error|ready";
• aria-busy="true" while loading or refreshing;
• data-meeko-refreshing during a refresh;
• with reserve, data-meeko-reserve and data-meeko-reserve-min.

A resource failure takes priority over another still loading, offering retry as soon as possible. If focus was on a node that disappears on a state change (the “Reintentar”, Retry, button), it moves to the container (tabindex="-1", without scrolling) instead of being lost.

Examples#

Multiple resources#

<script lang="ts">
const users = useApi("/api/users");
const stats = useRpcQuery("stats.summary");
</script>

<template>
  <MeekoAwait for="[users, stats]">
    <snippet name="pending"><p>Loading…</p></snippet>
    <p>{users.data.value.length} users · {stats.data.value.orders} orders</p>
  </MeekoAwait>
</template>

A discreet indicator during refresh#

Content receives refreshing; data stays on screen:

<script lang="ts">
const page = signal("1");
const orders = useApi("/api/orders", { query: { page } });
</script>

<template>
  <MeekoAwait for="orders">
    <snippet name="default" params="refreshing">
      <ul bind:class="refreshing ? 'dimmed' : undefined">
        <li each:of="orders.data.value" each:as="order" each:key="order.id">{order.total}</li>
      </ul>
    </snippet>
  </MeekoAwait>
  <button type="button" on:click="() => page.value = String(Number(page.value) + 1)">Next</button>
</template>

A skeleton with the same height#

reserve cannot predict height on the tab's first visit. A skeleton with the same rows, or an explicit minimum, also prevents that shift:

<MeekoAwait for="items" reserve="320px">
  <snippet name="pending"><ul class="skeleton"><li each:of="[1, 2, 3, 4]" each:as="row"></li></ul></snippet>
  <ul><li each:of="items.data.value" each:as="item" each:key="item.id">{item.name}</li></ul>
</MeekoAwait>

Translated messages#

<MeekoAwait for="items" bind:messages="{ error: 'Could not load the items.', retry: 'Retry' }">
  <ItemsList bind:items="items.data.value" />
</MeekoAwait>

Common mistakes#

Forget for#

<MeekoAwait><ItemsList bind:items="items.data.value" /></MeekoAwait>

meeko check reports MEEK116: <MeekoAwait> necesita for="recurso": el resultado de useApi o useRpcQuery sin await, o una lista, como for="[items, stats]".

<MeekoAwait for="items"><ItemsList bind:items="items.data.value" /></MeekoAwait>

Pass data instead of the resource#

<MeekoAwait for="items.data"><ItemsList bind:items="items.data.value" /></MeekoAwait>

meeko check reports TS2322: Type 'ReadonlySignal<Item[] | null>' is not assignable to type 'AwaitResource | readonly AwaitResource[]': the tag needs the whole resource, with data, error, pending and refresh. At runtime this would be a TypeError.

<MeekoAwait for="items"><ItemsList bind:items="items.data.value" /></MeekoAwait>

Read data outside the tag#

Only <MeekoAwait> content reads data as loaded.

<MeekoAwait for="items"><p>{items.data.value.length}</p></MeekoAwait>
<p>Total: {items.data.value.length}</p>

In the second <p>, meeko check reports TS18047: 'items.data.value' is possibly 'null'. Move the read inside, or check it:

<MeekoAwait for="items"><p>{items.data.value.length}</p><p>Total: {items.data.value.length}</p></MeekoAwait>

A reserve that is not a length#

<MeekoAwait for="items" reserve="mucho">…</MeekoAwait>

meeko check accepts it, but rendering throws TypeError: <MeekoAwait>: reserve must be empty or a CSS length such as reserve="320px", not "mucho".

<MeekoAwait for="items" reserve="20rem">…</MeekoAwait>

Notes#

• SSR. Without await, the request is not made on the server: HTML contains the pending snippet and aria-busy, and hydration changes nothing until data arrives. If the resource already has data on the server (an await useApi, also valid in for), HTML contains the content.
• await or <MeekoAwait>. For content visible on page load, await useApi(...) is better: SSR renders the data and nothing grows. <MeekoAwait> is for secondary data, off-screen regions or components mounted later.
• Reservation and CSP. Height is applied through a constructed stylesheet, without style attributes: it works with strict CSP. On a full load, a <head> script applies it before the first paint; the reserve="320px" minimum goes in a <style> with the request's nonce or, on a static site, its hash.
• Height memory. Stored in sessionStorage (meeko:await) by route, request and region order, keeping the 100 most recent. If the browser blocks storage, it lives while the page is open.
• Accessibility. aria-busy announces loading. The default error alert has role="alert"; add it to your error snippet too.
• MEEK117. meeko check warns about a page or layout rendering non-awaited useApi data in an each:of without handling loading; wrapping the list in <MeekoAwait> resolves it.

Related#

• Choosing in Meeko
• useApiReads a server/api GET endpoint from a component, with SSR, hydration without repeating the request, reactive reloading and contract types.
• useRpcQueryReads a server/rpc procedure from a component, with SSR, hydration, reactive input reloading and contract types.
• DataResourceDatos reactivos que devuelven useApi y useRpcQuery.
• useNavigationReturns the application's navigation state, with pending set to true while a new page loads.
• <MeekoAwait>Meeko as a full-stack framework
• Prevent layout shifts (CLS)Meeko as a full-stack framework
• Previous data during a reload: keepPreviousMeeko as a full-stack framework