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 @crossbuildui/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

Dependency

The Skeleton component uses expo-linear-gradient for the shimmer effect. Ensure it's installed in your project:
npm install expo-linear-gradient or yarn add expo-linear-gradient

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>

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.

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.

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).

Light Mode Default Placeholder: themeColors.default['100']
Dark Mode Default Placeholder: themeColors.default['200']
Light Mode Default Shimmer: 'rgba(255, 255, 255, 0.3)'
Dark Mode Default Shimmer: 'rgba(255, 255, 255, 0.1)'

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 Drawer