Skeleton

Loading placeholders you shape to match your content. They wait calmly and still, with no shimmer, then the real content switches on in their place, row by row.

Preview

Props Changes apply to the live preview above.

variant

active

TSX components/ui/skeleton/skeleton.tsx

import * as React from "react";
import { forwardRef } from "react";
import { View, type ViewProps } from "react-native";
import { SwitchOn, cn, rowDelay } from "@lumioui/core";

export interface SkeletonProps extends Omit<ViewProps, "className"> {
  className?: string;
  /**
   * "pulse" (default): a still, dim block.
   * @deprecated "shimmer" — now identical to "pulse". Nothing moves across a
   * placeholder: loading is still, dim structure that switches on when ready.
   */
  variant?: "pulse" | "shimmer";
  /** Kept for compatibility — the block is always still. Default true. */
  active?: boolean;
}

/**
 * Skeleton — one still, dim block in the exact shape of the content that
 * replaces it (DESIGN-TASTE §0b: loading is dim structure that switches on).
 * No sweep, no pulse. Pair it with `SkeletonSwitch`, which brings the real
 * content on in place.
 */
export const Skeleton = forwardRef<React.ElementRef<typeof View>, SkeletonProps>(function Skeleton(
  // `variant` and `active` no longer change anything; destructured so they never reach the View.
  { className, variant: _variant, active: _active, ...props },
  ref
) {
  return (
    <View
      ref={ref}
      className={cn("overflow-hidden rounded-lg bg-muted", className)}
      accessible={false}
      // Placeholder blocks announce nothing; the surrounding context carries the busy state.
      accessibilityElementsHidden
      importantForAccessibility="no-hide-descendants"
      aria-hidden
      {...props}
    />
  );
});
Skeleton.displayName = "Skeleton";

export interface SkeletonSwitchProps extends Omit<ViewProps, "className" | "children"> {
  /** false shows `placeholder`; true switches the real content on in place. */
  loaded: boolean;
  /** The dim layout shown while loading — the exact shape of `children`. */
  placeholder: React.ReactNode;
  /** The real content. Each top-level child switches on in turn on the row rhythm. */
  children: React.ReactNode;
  className?: string;
}

/**
 * SkeletonSwitch — loading that switches on. While `loaded` is false it shows
 * the still, dim layout; when it turns true the real content switches on
 * (dim → on) in hierarchy order, 40ms apart, in place — no pop, no layout
 * shift, nothing sweeping across.
 *   <SkeletonSwitch loaded={ready} placeholder={<InboxBones />}>{rows}</SkeletonSwitch>
 */
export const SkeletonSwitch = forwardRef<React.ElementRef<typeof View>, SkeletonSwitchProps>(function SkeletonSwitch(
  { loaded, placeholder, children, className, ...props },
  ref
) {
  return (
    <View ref={ref} className={cn("overflow-hidden", className)} accessibilityState={{ busy: !loaded }} {...props}>
      {loaded
        ? React.Children.toArray(children).map((child, i) => (
            <SwitchOn key={i} delay={rowDelay(i)}>
              {child}
            </SwitchOn>
          ))
        : placeholder}
    </View>
  );
});
SkeletonSwitch.displayName = "SkeletonSwitch";

TSX example.tsx

import { Skeleton } from "@/components/ui/skeleton/skeleton";

export function Example() {
  return (
    <Skeleton />
  );
}

Installation

npx @lumioui/cli add skeleton

Copy the source from the Code tab into your project
components/ui/skeleton/skeleton.tsxcomponents/ui/skeleton/index.ts
Update the import paths to match your project setup.

Usage

import { Skeleton, SkeletonSwitch } from "@/components/ui/skeleton/skeleton";

<Skeleton />

Also exported: SkeletonSwitch.

Examples

Inbox switch-on

A messaging inbox while threads sync.

npx @lumioui/cli add skeleton-pulse

TSX components/ui/skeleton/variants/pulse.tsx

import * as React from "react";
import { Image, Pressable, View } from "react-native";
import { Skeleton, SkeletonSwitch } from "../skeleton";
import { Icon } from "../../icon/icon";
import { Text } from "../../text/text";

const CHATS = [
  { name: "Hana Kobayashi", text: "Sent the floor plan, take a look", time: "9:41", img: 47, unread: true },
  { name: "Climbing crew", text: "Marcus: Saturday at 8 still on?", time: "9:12", img: 12, unread: true },
  { name: "Olu Adeyemi", text: "Haha yes, that one", time: "Yesterday", img: 15 },
  { name: "Sofía Marín", text: "Voice message · 0:42", time: "Mon", img: 20 },
];
/** How long the inbox takes to sync in the demo (the network's, not a UI duration). */
const SYNC_MS = 1400;

function Row({ first, lead, children }: { first: boolean; lead: React.ReactNode; children: React.ReactNode }) {
  return (
    <View className="flex-row items-center gap-3 pl-4">
      {lead}
      <View className={`flex-1 gap-1 py-3 pr-4 ${first ? "" : "border-t border-border"}`}>{children}</View>
    </View>
  );
}

/** SkeletonPulse — a messaging inbox while threads sync. The dim layout is the
 *  exact shape of the rows; when the sync lands the rows switch on in
 *  order, in place. Refresh brings the dim layout back. */
export function SkeletonPulse() {
  const [loaded, setLoaded] = React.useState(false);
  React.useEffect(() => {
    if (loaded) return;
    const id = setTimeout(() => setLoaded(true), SYNC_MS);
    return () => clearTimeout(id);
  }, [loaded]);

  return (
    <View className="w-full gap-3">
      <View className="flex-row items-center justify-between px-1">
        <Text className="text-3xl font-bold tracking-tight">Chats</Text>
        <Pressable
          onPress={() => setLoaded(false)}
          accessibilityRole="button"
          accessibilityLabel="Refresh chats"
          className="h-11 w-11 items-center justify-center rounded-full bg-card"
        >
          <Icon name="refresh" size="sm" color="foreground" />
        </Pressable>
      </View>

      <SkeletonSwitch
        loaded={loaded}
        className="w-full rounded-2xl bg-card"
        accessibilityLabel={loaded ? "Chats" : "Loading chats"}
        placeholder={CHATS.map((c, i) => (
          <Row key={c.name} first={i === 0} lead={<Skeleton className="h-12 w-12 rounded-full" />}>
            <View className="h-5 flex-row items-center justify-between">
              <Skeleton className="h-3.5 w-32 rounded" />
              <Skeleton className="h-3 w-10 rounded" />
            </View>
            <View className="h-5 justify-center">
              <Skeleton className={`h-3 rounded ${i % 2 ? "w-3/5" : "w-4/5"}`} />
            </View>
          </Row>
        ))}
      >
        {CHATS.map((c, i) => (
          <Row key={c.name} first={i === 0} lead={<Image source={{ uri: `https://i.pravatar.cc/150?img=${c.img}` }} className="h-12 w-12 rounded-full bg-muted" />}>
            <View className="h-5 flex-row items-center justify-between">
              <Text className="text-base font-semibold">{c.name}</Text>
              <Text className="text-xs text-muted-foreground">{c.time}</Text>
            </View>
            <View className="h-5 flex-row items-center gap-2">
              <Text variant="muted" className="flex-1" numberOfLines={1}>
                {c.text}
              </Text>
              {c.unread ? <View className="h-2.5 w-2.5 rounded-full bg-primary" /> : null}
            </View>
          </Row>
        ))}
      </SkeletonSwitch>
    </View>
  );
}

Store grid, long wait

A fashion store grid loading under a filter change.

npx @lumioui/cli add skeleton-shimmer

TSX components/ui/skeleton/variants/shimmer.tsx

import * as React from "react";
import { Image, Pressable, View } from "react-native";
import { Skeleton } from "../skeleton";
import { Text } from "../../text/text";

const photo = (id: string) => `https://images.unsplash.com/${id}?w=400&h=500&fit=crop&q=70&auto=format`;

const PRODUCTS = [
  { name: "Wool overcoat", brand: "Norse Field", price: "$340", id: "photo-1619603364937-8d7af41ef206" },
  { name: "Sherpa denim jacket", brand: "Arlo & Co", price: "$128", id: "photo-1543076447-215ad9ba6923" },
  { name: "Organic cotton tee", brand: "Common Thread", price: "$38", id: "photo-1489987707025-afc232f7ea0f" },
  { name: "Quilted puffer", brand: "Halden", price: "$215", id: "photo-1601924994987-69e26d50dc26" },
];

const FILTERS = ["New in", "Outerwear", "Knitwear"];

/** SkeletonShimmer — a fashion store grid loading under a filter change.
 *  The tiles wait as still, dim shapes however long the wait runs — nothing
 *  moves across them. Pick a filter to reload; tap the grid to let it land. */
export function SkeletonShimmer() {
  const [filter, setFilter] = React.useState("Outerwear");
  const [loaded, setLoaded] = React.useState(false);

  return (
    // The grid sits on a card sheet: muted placeholders read as shapes on
    // white, where on the grey canvas they nearly disappeared in light mode.
    <View className="w-full gap-4 rounded-3xl bg-card p-4">
      <View className="flex-row gap-2">
        {FILTERS.map((f) => {
          const on = f === filter;
          return (
            <Pressable
              key={f}
              onPress={() => {
                setFilter(f);
                setLoaded(false);
              }}
              accessibilityRole="button"
              accessibilityState={{ selected: on }}
              className={`h-9 justify-center rounded-full px-4 ${on ? "bg-primary" : "bg-secondary"}`}
            >
              <Text className={`text-sm font-medium ${on ? "text-primary-foreground" : "text-secondary-foreground"}`}>{f}</Text>
            </Pressable>
          );
        })}
      </View>

      <Pressable
        onPress={() => setLoaded(true)}
        disabled={loaded}
        accessibilityRole={loaded ? undefined : "button"}
        accessibilityLabel={loaded ? undefined : `Loading ${filter}. Tap to finish`}
        accessibilityState={{ busy: !loaded }}
        className="w-full flex-row flex-wrap justify-between gap-y-5"
      >
        {PRODUCTS.map((p) => (
          <View key={p.name} className="w-[48%] gap-2">
            {loaded ? (
              <Image source={{ uri: photo(p.id) }} className="aspect-[4/5] w-full rounded-2xl bg-muted" />
            ) : (
              <Skeleton className="aspect-[4/5] w-full rounded-2xl" />
            )}
            {loaded ? (
              <View className="gap-0.5">
                <Text className="text-[15px] font-medium" numberOfLines={1}>{p.name}</Text>
                <Text variant="muted" numberOfLines={1}>{p.brand}</Text>
                <Text className="text-[15px] font-semibold tabular-nums">{p.price}</Text>
              </View>
            ) : (
              <View className="gap-2 pt-1">
                <Skeleton className="h-3.5 w-4/5 rounded" />
                <Skeleton className="h-3 w-1/2 rounded" />
                <Skeleton className="h-3.5 w-1/4 rounded" />
              </View>
            )}
          </View>
        ))}
      </Pressable>
    </View>
  );
}

API reference

`Skeleton`

Prop Type Default

className string —

variant "pulse" | "shimmer"

"pulse" (default): a still, dim block. @deprecated "shimmer" — now identical to "pulse". Nothing moves across a placeholder: loading is still, dim structure that switches on when ready.

—

active boolean

Kept for compatibility — the block is always still. Default true.

—

`SkeletonSwitch`

Prop Type Default

loaded* boolean

false shows placeholder; true switches the real content on in place.

—

placeholder* React.ReactNode

The dim layout shown while loading — the exact shape of children.

—

children* React.ReactNode

The real content. Each top-level child switches on in turn on the row rhythm.

—

className string —

Primitives

Composed

Screens

Skeleton

Preview

Installation

Usage

Examples

Inbox switch-on

Store grid, long wait

API reference

`Skeleton`

`SkeletonSwitch`

Preview

Installation

Usage

Examples

Inbox switch-on

Store grid, long wait

API reference

Skeleton

SkeletonSwitch

Related

`Skeleton`

`SkeletonSwitch`