UI Patterns

Copy‑paste components and patterns for common Base MiniApp flows

UI Patterns

Practical, copy‑pasteable patterns aligned with the Design Principles and Quality Bar. Use these to ship fast and consistently.

First‑run value screen

export function FirstRun() {
  return (
    <section className="first-run">
      <h1>Play daily trivia, win USDC</h1>
      <p>Test your knowledge and climb the leaderboard</p>
      <PrimaryButton>Start playing</PrimaryButton>
      <TextLink href="#leaderboard">View leaderboard</TextLink>
    </section>
  );
}

Guidelines:

• Keep title ≤ 80 chars; describe outcome
• One primary action; one secondary pathway
• No auth gate on first screen

List + skeleton loading

function ListSkeleton() {
  return (
    <div className="list-skeleton">
      {[...Array(6)].map((_, i) => (
        <div key={i} className="row" />
      ))}
    </div>
  );
}

export function ListExample({ items, isLoading }) {
  if (isLoading) return <ListSkeleton />;
  if (!items?.length) return <EmptyState />;

  return (
    <ul className="list">
      {items.map((item) => (
        <li key={item.id} className="card">
          <h3>{item.title}</h3>
          <p>{item.subtitle}</p>
        </li>
      ))}
    </ul>
  );
}

CSS excerpt:

.list-skeleton .row {
  height: 56px;
  border-radius: 12px;
  background: linear-gradient(90deg, #eee, #f5f5f5, #eee);
  animation: pulse 1.2s infinite;
}
@keyframes pulse {
  0% {
    background-position: 0% 0;
  }
  100% {
    background-position: 100% 0;
  }
}

Empty state

function EmptyState() {
  return (
    <div className="empty">
      <Icon name="inbox" />
      <h3>No items yet</h3>
      <p>Try creating your first item to get started</p>
      <PrimaryButton>Create item</PrimaryButton>
    </div>
  );
}

Checklist:

• Explain situation plainly
• Provide one clear next action
• Avoid technical language

Toast vs modal

Use toast for lightweight confirmation; modal for single focused tasks.

// Toast
showToast({ title: "Saved", description: "Your changes were saved" });

// Modal
<Modal>
  <h3>Confirm transfer</h3>
  <p>Send 5 USDC to @alex?</p>
  <PrimaryButton>Send</PrimaryButton>
  <SecondaryButton>Cancel</SecondaryButton>
</Modal>;

Rules:

• Toasts auto-dismiss; do not block navigation
• Modals: one decision, max two actions, escape route always present

Optimistic action with undo

async function onDelete(itemId: string) {
  removeItemLocally(itemId); // optimistic
  const ok = await api.delete(itemId).catch(() => false);
  if (!ok) {
    restoreItem(itemId);
    showToast({ title: "Couldn’t delete", description: "Try again" });
  } else {
    showToast({
      title: "Deleted",
      action: { label: "Undo", onClick: () => restoreItem(itemId) },
    });
  }
}

Auth prompt pattern

AuthPrompt({
  title: "Continue with Base",
  reason: "Save your progress and compete with friends",
  benefits: ["Track streaks", "Earn rewards", "Share achievements"],
});

Motion

• 200–300ms ease‑out for transitions
• Respect prefers‑reduced‑motion
• Avoid blocking progress with full‑screen loaders

Safe areas

Use env(safe-area-inset-*) and provide padding tokens as in Design Principles.

Pattern checklist

• Clear value, single primary action
• Skeletons for loading, meaningful empty states
• Non‑blocking feedback; accessible focus/roles
• Works in light/dark; respects safe areas and touch targets