PlSkeleton

The shape of something that has not loaded yet. It reserves the space the real thing will take, which is the whole job. A spinner cannot do that.

React

import { PlSkeleton } from 'plass-ui';

<PlSkeleton lines={3} label="Loading the article" />;
<PlSkeleton shape="circle" />;
<PlSkeleton shape="rect" height={120} />;

import 'package:plass_ui/plass_ui.dart';

const PlSkeleton(lines: 3, label: 'Loading the article');
const PlSkeleton(shape: PlSkeletonShape.circle);
const PlSkeleton(shape: PlSkeletonShape.rect, height: 120);

Props

Prop	Type	Default	Description
shape	'line' | 'rect' | 'circle'	'line'	What the placeholder is standing in for. line is a run of text, rect a block, circle an avatar. Each is sized off the ladder the real component uses
lines	number	1	How many lines to draw for shape="line". The last one is drawn short, the way the last line of a paragraph is, so a block of them reads as prose rather than as a barcode
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The scale of the thing being stood in for: the type scale for a line, the diameter for a circle, the default block height for a rect
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	Colour family. Worth leaving at secondary: a placeholder that carries a semantic colour is saying something about content that has not arrived yet
width	number | string	—	An explicit width. Numbers are pixels
height	number | string	—	An explicit height. Numbers are pixels
animated	boolean	true	The travelling highlight. Turn it off for a page holding dozens, or where motion becomes noise. A reduced-motion preference already swaps the sweep for a colour pulse, so this is not the accessibility switch
label	string	—	What a screen reader is told. Without it the placeholder is aria-hidden, because a dozen boxes each announcing themselves is worse than silence. Give the *one* that stands for the whole region a label and it becomes a live status
render	useRender.RenderProp	—	Renders something other than a div

Prop	Type	Default	Description
shape	PlSkeletonShape	PlSkeletonShape.line	What the placeholder is standing in for. line is a run of text, rect a block, circle an avatar. Each is sized off the ladder the real component uses
lines	int	1	How many lines to draw for shape="line". The last one is drawn short, the way the last line of a paragraph is, so a block of them reads as prose rather than as a barcode
sizeshared	PlassSize	PlassSize.md	The scale of the thing being stood in for: the type scale for a line, the diameter for a circle, the default block height for a rect
colorshared	PlassColor	PlassColor.secondary	Colour family. Worth leaving at secondary: a placeholder that carries a semantic colour is saying something about content that has not arrived yet
width	double?	—	An explicit width. Numbers are pixels
height	double?	—	An explicit height. Numbers are pixels
animated	bool	true	The travelling highlight. Turn it off for a page holding dozens, or where motion becomes noise. A reduced-motion preference already swaps the sweep for a colour pulse, so this is not the accessibility switch
label	String?	—	What a screen reader is told. Without it the placeholder stays out of the semantics tree; give the one that stands for the whole region a label and it becomes a live region with that name

Every native <div> attribute passes straight through. color is excluded from the pass-through because it is a Plass prop here.

width and height are doubles, logical pixels, as everywhere else in the package.

There is no variant, no elevation and no density. A skeleton is deliberately not made of glass: every other sheet in the library is translucent over a blurred backdrop because it is a thing sitting on the page, and a skeleton is the opposite, the shape of something that is not there yet. So it is a flat tint and nothing else, which also keeps a page of thirty placeholders from asking for thirty backdrop filters.

What the shared axes (size color) mean across the library is in prop conventions.

Examples

shape

The three shapes are the three things a layout is made of (a run of text, a block and a circle), and each is sized off the ladder the real component uses. A md line is as tall as md type, and a md circle is exactly a PlAvatar at md.

lines draws a stack of bars rather than one striped box, so the gaps between them are real gaps: text has leading. The last one is drawn short, the way the last line of a paragraph is.

React

import { PlSkeleton } from 'plass-ui';

export default function SkeletonShapes() {
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <PlSkeleton />
      <PlSkeleton lines={4} />
      <PlSkeleton shape="rect" />
      <PlSkeleton shape="circle" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class SkeletonShapes extends StatelessWidget {
  const SkeletonShapes({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        spacing: 24,
        children: <Widget>[
          PlSkeleton(),
          PlSkeleton(lines: 4),
          PlSkeleton(shape: PlSkeletonShape.rect),
          PlSkeleton(shape: PlSkeletonShape.circle),
        ],
      ),
    );
  }
}

Standing in for the real thing

The point is that nothing moves when the content arrives. A card that grows by 200px when its image loads has shifted everything below it while somebody was reading.

React

import { useState } from 'react';
import { PlAvatar, PlButton, PlSkeleton, PlTypography } from 'plass-ui';

export default function SkeletonMatching() {
  const [loaded, setLoaded] = useState(false);

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PlButton size="sm" variant="glass" color="secondary" onClick={() => setLoaded(!loaded)}>
        {loaded ? 'Show the placeholder' : 'Show the real thing'}
      </PlButton>

      <div className="flex items-center gap-3">
        {loaded ? (
          <PlAvatar name="Nadia Rowan" src="/samples/avatars/nadia-rowan.webp" />
        ) : (
          <PlSkeleton shape="circle" />
        )}
        <div className="flex min-w-0 flex-1 flex-col gap-1">
          {loaded ? (
            <>
              <PlTypography weight="semibold">Nadia Rowan</PlTypography>
              <PlTypography level="caption">Design systems</PlTypography>
            </>
          ) : (
            <PlSkeleton lines={2} />
          )}
        </div>
      </div>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class SkeletonMatching extends StatefulWidget {
  const SkeletonMatching({super.key});

  @override
  State<SkeletonMatching> createState() => _SkeletonMatchingState();
}

class _SkeletonMatchingState extends State<SkeletonMatching> {
  bool _loaded = false;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          PlButton(
            size: PlassSize.sm,
            variant: PlassVariant.glass,
            color: PlassColor.secondary,
            onPressed: () => setState(() => _loaded = !_loaded),
            child: Text(_loaded ? 'Show the placeholder' : 'Show the real thing'),
          ),
          Row(
            spacing: 12,
            children: <Widget>[
              if (_loaded)
                const PlAvatar(
                  name: 'Nadia Rowan',
                  image: NetworkImage('/samples/avatars/nadia-rowan.webp'),
                )
              else
                const PlSkeleton(shape: PlSkeletonShape.circle),
              Expanded(
                child: _loaded
                    ? const Column(
                        crossAxisAlignment: CrossAxisAlignment.start,
                        mainAxisSize: MainAxisSize.min,
                        spacing: 4,
                        children: <Widget>[
                          PlTypography('Nadia Rowan', weight: PlTypographyWeight.semibold),
                          PlTypography('Design systems', level: PlTypographyLevel.caption),
                        ],
                      )
                    : const PlSkeleton(lines: 2),
              ),
            ],
          ),
        ],
      ),
    );
  }
}

animated

The travelling highlight is on by default. Turn it off for a page holding dozens of placeholders, or where the wait is expected to be long enough that motion becomes noise.

This is not the accessibility switch: a reduced-motion preference already replaces the sweep with a colour pulse without being asked.

React

import { PlSkeleton } from 'plass-ui';

export default function SkeletonAnimated() {
  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <PlSkeleton lines={2} />
      <PlSkeleton lines={2} animated={false} />
      <PlSkeleton shape="rect" height={56} color="primary" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class SkeletonAnimated extends StatelessWidget {
  const SkeletonAnimated({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.stretch,
        spacing: 20,
        children: <Widget>[
          PlSkeleton(lines: 2),
          PlSkeleton(lines: 2, animated: false),
          PlSkeleton(shape: PlSkeletonShape.rect, height: 56, color: PlassColor.primary),
        ],
      ),
    );
  }
}

size

React

import { PlSkeleton } from 'plass-ui';

export default function SkeletonSizes() {
  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <div key={size} className="flex items-center gap-4">
          <span className="w-8 shrink-0 text-xs text-(--plass-muted-fg)">{size}</span>
          <PlSkeleton size={size} lines={2} />
          <PlSkeleton size={size} shape="circle" />
        </div>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class SkeletonSizes extends StatelessWidget {
  const SkeletonSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        mainAxisSize: MainAxisSize.min,
        spacing: 20,
        children: <Widget>[
          for (final size in PlassSize.values)
            Row(
              spacing: 16,
              children: <Widget>[
                SizedBox(
                  width: 32,
                  child: PlTypography(size.name, level: PlTypographyLevel.caption),
                ),
                Expanded(child: PlSkeleton(size: size, lines: 2)),
                PlSkeleton(size: size, shape: PlSkeletonShape.circle),
              ],
            ),
        ],
      ),
    );
  }
}

Accessibility

• Unlabelled, a placeholder is aria-hidden and says nothing. A dozen boxes each announcing themselves is worse than silence.
• Give the one skeleton that stands for the whole region a label, and it becomes a role="status" with aria-busy, one announcement for one wait.
• Under prefers-reduced-motion the highlight stops travelling and the placeholder pulses in colour instead. It is not stopped outright, because a skeleton that holds still is indistinguishable from an empty box that finished loading with nothing in it.

• Unlabelled, a placeholder is excluded from the semantics tree and says nothing. A dozen boxes each announcing themselves is worse than silence.
• Give the one skeleton that stands for the whole region a label, and it becomes a live region with that name, one announcement for one wait.
• When the platform has animations turned off (MediaQuery.disableAnimations) the highlight stops travelling and the placeholder pulses in colour instead. It is not stopped outright, because a skeleton that holds still is indistinguishable from an empty box that finished loading with nothing in it.

Differences from the React build

React	Flutter	Why
role="status" + aria-busy	a named live region	Flutter has liveRegion and no busy. The name is what carries the wait.
prefers-reduced-motion	MediaQuery.disableAnimations	The platform's own signal.
width/height as a CSS length	double	Logical pixels. A fraction of the parent is a FractionallySizedBox around the placeholder.
render	—	Flutter has no polymorphic element.
className, style	—	There is no class list and no style attribute to pass through.

The sweep is drawn differently and looks the same: CSS animates a 60%-wide pseudo-element across the box, and here the same three-stop gradient is slid across the box by a GradientTransform. One widget instead of two, and no second box to lay out per placeholder.