Skeleton

The Skeleton component provides a placeholder loading state, visually indicating where content will appear once data is fetched. It enhances user experience by managing expectations during loading times.

Installation

$ cbui-cli install skeleton

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

MyComponent.tsx

import { Skeleton } from '@/crossbuildui/skeleton';
import type { SkeletonSlotsStyles } from '@/crossbuildui/skeleton'; // Optional: for type safety

Dependencies

The Skeleton component uses expo-linear-gradient for the shimmer effect. Ensure it's installed in your project. If using the isGlass prop, expo-blur is also required.

Skeleton Component

Basic Usage

Control the visibility of the skeleton or actual content using the isLoaded prop. The style prop on the Skeleton component defines the shape and size of the placeholder.

MyComponent.tsx

function MyComponent() {
  const [isLoaded, setIsLoaded] = useState(false);

  useEffect(() => {
    // Simulate data fetching
    const timer = setTimeout(() => setIsLoaded(true), 3000);
    return () => clearTimeout(timer);
  }, []);

  return (
    <View>
      <Skeleton isLoaded={isLoaded} style={{ width: 200, height: 20, borderRadius: 4, marginBottom: 8 }}>
        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>Content Loaded!</Text>
      </Skeleton>
      <Skeleton isLoaded={isLoaded} style={{ width: '80%', height: 16, borderRadius: 4 }}>
        <Text>This is some paragraph text that appears after loading.</Text>
      </Skeleton>
    </View>
  );
}

Custom Shapes and Layouts

Apply styles directly via the style prop to create various shapes (e.g., circles, specific line heights, image placeholders). You can compose multiple Skeletons to mimic complex layouts.

MyComponent.tsx

<View style={{ gap: 16 }}>
  {/* Circle Skeleton */}
  <Skeleton isLoaded={false} style={{ width: 50, height: 50, borderRadius: 25 }}>
    <Image source={{ uri: 'https://via.placeholder.com/50' }} style={{ width: 50, height: 50, borderRadius: 25 }} />
  </Skeleton>

  {/* Multiple lines for a text block */}
  <Skeleton isLoaded={false} style={{ width: '90%', height: 18, borderRadius: 4, marginBottom: 6 }}>
    <Text style={{ fontSize: 16 }}>A line of text.</Text>
  </Skeleton>
  <Skeleton isLoaded={false} style={{ width: '70%', height: 18, borderRadius: 4 }}>
    <Text style={{ fontSize: 16 }}>Another shorter line.</Text>
  </Skeleton>
</View>

Disable Animation

If you prefer a static placeholder without the shimmer animation, set disableAnimation to true.

MyComponent.tsx

<Skeleton 
    isLoaded={false} /* Keep false to show skeleton */ 
    disableAnimation 
    style={{ width: 150, height: 20, borderRadius: 4 }}
>
  {/* Content won't be shown as isLoaded is false */}
</Skeleton>

Custom Colors

Override the default theme-based colors for the placeholder background and shimmer effect using placeholderBackgroundColor and shimmerColor props.

MyComponent.tsx

<View style={{ gap: 10 }}>
  <Skeleton
    isLoaded={false}
    style={{ width: '100%', height: 24, borderRadius: 4 }}
    placeholderBackgroundColor="lightblue"
    shimmerColor="rgba(200, 200, 255, 0.5)"
  >
    {/* Content */}
  </Skeleton>
  <Skeleton
    isLoaded={false}
    style={{ width: '100%', height: 24, borderRadius: 4 }}
    placeholderBackgroundColor="#555" // Dark placeholder
    shimmerColor="rgba(150, 150, 150, 0.3)" // Darker shimmer
  >
    {/* Content */}
  </Skeleton>
</View>

Glass Effect

Apply a frosted glass effect to the skeleton placeholder using isGlass. Customize it with glassIntensity (0-100, this is the base for a pulsing animation) and glassTint ('light', 'dark', 'default'). When isGlass is true, placeholderBackgroundColor is set to transparent, and the shimmer effect adapts to be more subtle on the blurred background. The glass intensity also has a subtle pulsing animation by default unless disableAnimation is true.

MyComponent.tsx

<View style={{ gap: 16, padding: 10, backgroundColor: 'rgba(0,0,0,0.2)' /* Darker bg to see light glass */ }}>
  <Skeleton
    isLoaded={false} /* Keep false to show skeleton */
    isGlass
    glassTint="light"
    glassIntensity={70} // Base intensity for pulsing animation
    style={{ width: '90%', height: 20, borderRadius: 4, marginBottom: 8 }}
  >
    {/* Content */}
  </Skeleton>
  <Skeleton
    isLoaded={false}
    isGlass
    glassTint="dark"
    glassIntensity={40}
    style={{ width: '70%', height: 18, borderRadius: 4 }}
  >
    {/* Content */}
  </Skeleton>
</View>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Actual content to display once loading is complete.
`isLoaded`	`boolean`	`false`	If true, children are rendered; otherwise, skeleton is shown.
`disableAnimation`	`boolean`	`false`	If true, shimmer animation is disabled.
`style`	`StyleProp<ViewStyle>`	-	Defines the shape/size of the skeleton placeholder.
`styles`	`SkeletonSlotsStyles`	-	Custom styles for internal slots (placeholder, shimmer).
`shimmerColor`	`string`	Theme-based	Color of the shimmer effect (e.g., 'rgba(255,255,255,0.3)').
`placeholderBackgroundColor`	`string`	Theme-based	Background color of the placeholder.
`isGlass`	`boolean`	`false`	Apply glassmorphism effect to the placeholder background.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the glass effect.
`glassIntensity`	`number`	`30`	Base intensity (0-100) for the glass effect's pulsing animation.

Styling

The primary way to define the skeleton's appearance (shape, size) is through the style prop. This style is applied to the main placeholder view.

For more granular control, the styles prop accepts an object with keys for internal slots:

placeholder: Styles applied to the placeholder View that contains the shimmer. The style prop is merged with this. Ensure overflow: 'hidden' is maintained if overriding.
shimmer: Styles applied to the Animated.View containing the LinearGradient for the shimmer. This view is absolutely positioned to fill the placeholder. The shimmer effect itself comes from the gradient colors, so direct background styling here might obscure it. When isGlass is true, the shimmer is a more subtle pulsing animation of the BlurView's intensity rather than a sweeping gradient.

Placeholder Styling

The style prop is crucial as it dictates the dimensions and border radius of the skeleton. The placeholder view has overflow: 'hidden' by default to correctly clip the sweeping shimmer animation.

MyComponent.tsx

<Skeleton
  isLoaded={false}
  style={{ width: '100%', height: 40, borderWidth: 2, borderColor: 'blue' }} // Base shape
  styles={{
    placeholder: { // Styles for the placeholder View
      opacity: 0.7,
    },
    shimmer: { // Styles for the LinearGradient View
      // Note: Shimmer effect is achieved by LinearGradient colors,
      // direct backgroundColor here might cover the gradient.
      // Use for layout or other non-color style adjustments if needed.
    }
  }}
  placeholderBackgroundColor="lightgreen"
  shimmerColor="rgba(152, 251, 152, 0.6)"
>
  {/* Content */}
</Skeleton>

Theming

The Skeleton component is theme-aware. By default, placeholderBackgroundColor and shimmerColor adapt to the current theme (light/dark mode). If isGlass is true, placeholderBackgroundColor is set to transparent.

Light Mode Default Placeholder: themeColors.default['100']
Dark Mode Default Placeholder: themeColors.default['200']
Default Shimmer (non-glass): Light mode 'rgba(255, 255, 255, 0.3)', Dark mode 'rgba(255, 255, 255, 0.1)'.
Default Shimmer (glass): Light mode 'rgba(0, 0, 0, 0.08)', Dark mode 'rgba(255, 255, 255, 0.15)'. This is for the gradient over the blur, though the primary glass animation is intensity pulsing.

You can override these defaults by providing explicit values to the placeholderBackgroundColor and shimmerColor props.

Accessibility

Skeletons are primarily visual cues for loading states.

They don't typically have direct interactive roles or explicit accessibility labels themselves, as their purpose is to represent content that is not yet available.
Ensure that the surrounding context or a screen reader announcement indicates that content is loading. For example, a page title or a live region update could inform users about the loading state.
Once content is loaded (isLoaded=), ensure the actual content (children) is fully accessible.

Progress Loader