Skeleton

Overview

The Skeleton component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Skeletons are perceived as faster than spinners because they show the layout structure before content arrives. They reduce perceived wait time.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { Skeleton } from '@byteion/react';

export default function SkeletonDemo() {
  return (
    <div className="max-w-sm space-y-3 p-6">
      <Skeleton className="h-32 w-full rounded-xl" />
      <Skeleton className="h-4 w-3/4" />
      <Skeleton className="h-4 w-1/2" />
      <div className="flex items-center gap-3 pt-2">
        <Skeleton className="h-10 w-10 rounded-full" />
        <Skeleton className="h-4 w-32" />
      </div>
    </div>
  );
}

<script setup lang="ts">
import { Skeleton } from '@byteion/vue';
</script>

<template>
  <div class="max-w-sm space-y-3 p-6">
    <Skeleton class="h-32 w-full rounded-xl" />
    <Skeleton class="h-4 w-3/4" />
    <Skeleton class="h-4 w-1/2" />
    <div class="flex items-center gap-3 pt-2">
      <Skeleton class="h-10 w-10 rounded-full" />
      <Skeleton class="h-4 w-32" />
    </div>
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• loading — Action in progress — spinner replaces icon, button is disabled.
• default — Resting appearance before interaction.
• hover — Pointer is over the element — visual feedback via color or shadow.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

Usage guidelines

• Match the shape of the loaded content.
• Use shimmer animation.
• Keep dimensions identical to final content.

Do and Don't

Accessibility

Wrap with aria-busy="true" and aria-label="Loading". Hide from screen readers when loaded.

Customization

Color uses muted background with shimmer animation.

import { cva, cn, type VariantProps } from '@byteion/react';

const mySkeleton = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof mySkeleton>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const mySkeleton = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => mySkeleton({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Static HTML. Remove when content is loaded.

export interface SkeletonProps
  extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>,
    VariantProps<typeof skeleton> {
  /** Tailwind width utility (or CSS width via style). Default `w-full`. */
  width?: string;
  /** Tailwind height utility (or CSS height via style). Default `h-3`. */
  height?: string;
}

cva('bg-muted', {
  variants: {
    rounded: {
      none:    'rounded-none',
      sm:      'rounded',
      md:      'rounded-md',
      lg:      'rounded-lg',
      xl:      'rounded-xl',
      full:    'rounded-full',
    },
    animation: {
      pulse:   'motion-safe:animate-pulse-soft',
      shimmer: 'bg-shimmer motion-safe:animate-shimmer dark:bg-shimmer-dark',
      none:    '',
    },
  },
  defaultVariants: { rounded: 'sm', animation: 'pulse' },
})

export interface SkeletonProps {
  rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
  animation?: 'pulse' | 'shimmer' | 'none';
  /** Tailwind width utility (or CSS width via style). Default `w-full`. */
  width?: string;
  /** Tailwind height utility (or CSS height via style). Default `h-3`. */
  height?: string;
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Spinner
• Progress
• Empty State