Quick start

This page turns a common React data component into declarative utilinent markup.

Start in an existing React 18 or newer application. Utilinent does not create an app, fetch the users, or own the loading state; this example only replaces the rendering branches.

1. Install

pnpm add @ilokesto/utilinent

react is a peer dependency and should already be installed by the application. Components are imported from the package root; hooks live under the ./hooks subpath.

import { For, Show } from '@ilokesto/utilinent';

2. Start from the ordinary React version

type User = { id: string; name: string };

export function UserList({ users, loading }: { users?: User[]; loading: boolean }) {
  if (loading) return <p>Loading users...</p>;
  if (!users || users.length === 0) return <p>No users found.</p>;

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

This is fine for one component. As screens grow, the same loading, empty, and list branches are often repeated inline.

3. Use Show for the loading branch

import { Show } from '@ilokesto/utilinent';

<Show when={!loading} fallback={<p>Loading users...</p>}>
  {/* content when loading is false */}
</Show>

Show renders children when when is truthy and fallback otherwise.

4. Use For for the array branch

import { For } from '@ilokesto/utilinent';

<For.ul each={users} fallback={<p>No users found.</p>}>
  {(user) => <li key={user.id}>{user.name}</li>}
</For.ul>

For.ul renders the list items inside a real <ul>. Use For without a tag when you do not want a wrapper element.

5. Compose the final component

import { For, Show } from '@ilokesto/utilinent';

type User = { id: string; name: string };

export function UserList({ users, loading }: { users?: User[]; loading: boolean }) {
  return (
    <Show when={!loading} fallback={<p>Loading users...</p>}>
      <For.ul each={users} fallback={<p>No users found.</p>}>
        {(user) => <li key={user.id}>{user.name}</li>}
      </For.ul>
    </Show>
  );
}

Render <UserList loading users={undefined} /> to see Loading users.... Change it to <UserList loading={false} users={[]} /> to see No users found., then pass one or more users to get a <ul> of names.

6. Extend the completed example when needed

The following fragment replaces the return value in the completed component above. UserListSkeleton, EmptyUsers, and UserRow are application components that you provide.

<Show.section
  when={!loading}
  fallback={<UserListSkeleton />}
  aria-busy={loading}
>
  <For.ul each={users} fallback={<EmptyUsers />}> 
    {(user) => <UserRow key={user.id} user={user} />}
  </For.ul>
</Show.section>

Proxy tags such as Show.section and For.ul pass DOM props and refs to the underlying element.

Next steps

Learn the mental model in Core concepts.
Read exact behavior in Show and For.
Use Async data guide for loading/error/success layouts.

On this page