Loader

The Loader component is used to display visual loading indicators with various animation styles and configurations.

Installation

$ cbui-cli install @crossbuildui/loader

Ensure expo-blur is installed if using glass variant. Loader also depends on react-native-reanimated for animations.

Import

index.tsx

import Loader from '@/crossbuildui/loader';

Basic Usage

index.tsx

<Loader isVisible text="Loading..." />

Using LoaderProvider (Optional)

Wrap your app in LoaderProvider to pass a global configuration for size, color, etc.

App.tsx

<LoaderProvider globalConfig={{ size: 'sm', color: 'secondary' }}>
  <App />
</LoaderProvider>

You can access theme, layout and loader config via useLoaderContext():

MyComponent.tsx

const { themeColors, layoutConfig, globalLoaderConfig } = useLoaderContext();

Variants

Loader supports multiple animation variants:spinner, pulse, dots, bars, wave, skeleton, and custom.

index.tsx

<Loader isVisible variant="spinner" text="Loading..." />
<Loader isVisible variant="pulse" />
<Loader isVisible variant="dots" elementCount={4} />
<Loader isVisible variant="bars" />
<Loader isVisible variant="wave" />
<Loader isVisible variant="skeleton" />

Sizes

Choose from xs, sm, md, lg, or xl sizes.

index.tsx

<Loader isVisible size="xs" />
<Loader isVisible size="sm" />
<Loader isVisible size="md" />
<Loader isVisible size="lg" />
<Loader isVisible size="xl" />

Glass Mode

Enable glassmorphism using the isGlass prop along with glassTint and glassIntensity. Works best on images or textured backgrounds.

index.tsx

<Loader
  isVisible
  isGlass
  glassTint="light"
  glassIntensity={40}
  variant="pulse"
  text="Glass Effect"
  subtitle="Beautiful glassmorphism background"
/>

Inline Toggle Example

You can use loaders in inline mode conditionally based on state:

index.tsx

<Loader
  isVisible={loading}
  variant="dots"
  position="inline"
  text="Loading content..."
/>

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`isVisible`	`boolean`	`false`	Show or hide the loader.
`variant`	`'spinner' \| 'pulse' \| 'dots' \| 'bars' \| 'wave' \| 'skeleton' \| 'custom'`	`'spinner'`	Loader animation style.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size of loader.
`color`	`ColorShade \| string`	`'primary'`	Color of loader elements.
`position`	`'top' \| 'bottom' \| 'center' \| 'inline'`	`'center'`	Position of the loader within the screen.
`text`	`string`	-	Text below loader.
`subtitle`	`string`	-	Subtitle below text.
`children`	`ReactNode`	-	Custom loader element (for variant='custom').
`elementCount`	`number`	`3`	Number of elements (dots, bars, etc).
`disableAnimation`	`boolean`	`false`	Disable animation.
`animationDuration`	`number`	`1500`	Duration of animation in ms.
`showOverlay`	`boolean`	`false`	Show overlay background.
`overlayOpacity`	`number`	`0.5`	Opacity for the overlay.
`glassTint`	`'default' \| 'light' \| 'dark'`	`-`	Tint color for blur background (glass mode).
`glassIntensity`	`number`	`30`	Blur intensity for glass mode.
`isGlass`	`boolean`	`false`	Enable glass (blur) background.
`fullScreen`	`boolean`	`false`	Expand loader to full screen.
`icon`	`ReactNode`	-	Custom icon for spinner variant.
`onAnimationComplete`	`() => void`	-	Callback after animation ends.
`styles`	`Partial<LoaderSlotStyles>`	-	Custom style overrides per slot.
`style`	`StyleProp<ViewStyle>`	-	Style for the loader root container.

Styling

Customize the loader layout and appearance using:

style: to override the root container.
styles: an object to override slot styles like base, overlay, loader, text, subtitle, and element.

Accessibility

The Loader component is accessible by default and uses ActivityIndicator where possible. You can also set custom labels if needed using wrapping elements.

Custom Animations

You can disable animations using disableAnimation or configure duration using animationDuration. Each variant has unique native-driver-powered animations, including spin, pulse, and interpolated dots.

Skeleton Drawer