Skip to main content
Skeleton provides a placeholder shape with theme colors and a moving highlight. Compose shapes in the layout of the content being loaded. The application owns loading state and feature-specific layouts.

Usage

Skeleton renders as a block and never grows wider than its container. Use layout="inline" to place a placeholder inside a line of text. Numeric dimensions use pixels. CSS lengths such as percentages and em are also supported. Without dimensions, the placeholder fills the available width and uses the inherited font height. Use equal dimensions and borderRadius="50%" for a circle. SKELETON_HEIGHT_SIZES provides shared heights for xs (13px), s (16px), m (24px), l (32px) and xl (40px). Keep layout-specific dimensions in the application. Each Skeleton renders one placeholder. Keep repeated lines, text-line spacing and loading regions in application components that wrap the primitive.

Motion and accessibility

Skeletons are decorative and have aria-hidden="true" by default. Keep loading announcements in a host-owned status region instead of announcing each shape. Skeleton does not accept children. The highlight moves from left to right on a 1.5-second ease-in-out loop and is hidden when the user prefers reduced motion. Pass animated={false} for a static placeholder.

Composition and theme

Native props, className, style and ref target the placeholder span. Use render to compose another element. Explicit native styles override dimension and color props. The base and highlight colors default to the theme tertiary background and lighter transparent background. Use baseColor, highlightColor and borderRadius to override them. Corners stay round, including when the theme uses squircles. The default radius uses the smRound theme token (4px). Pass themeCssVariables.border.radius.mdRound from twenty-ui/theme for 8px corners. Custom pixel and CSS radii remain supported, including borderRadius={80} for a narrow capsule and borderRadius="50%" for a circle. No skeleton-specific provider or stylesheet import is needed after loading twenty-ui/style.css and the UI theme.

Props

boolean
default:"true"
Animate the highlight by default. Reduced-motion preferences always disable animation.
Booleanish
Placeholders are decorative and hidden from assistive technology by default. The host owns loading announcements.
BackgroundColor
Placeholder background color. Defaults to the theme tertiary background.
BorderRadius<string | number>
Round corner radius in pixels or a CSS length. Defaults to the 4px smRound theme token. Use mdRound for 8px corners or a custom radius for circles and capsules.
string
CSS class merged with the placeholder class.
Height<string | number>
Placeholder height in pixels or a CSS length. Defaults to the inherited font height.
BackgroundColor
Animated highlight color. Defaults to the theme lighter transparent background.
"block" | "inline"
default:"block"
block renders a block without a text node. inline sizes and aligns the placeholder like a line of text.
Ref<HTMLSpanElement>
Ref to the placeholder span, or the element supplied through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Element or render callback composed through Base UI useRender.
CSSProperties
Native styles merged with the placeholder dimensions and colors. Explicit styles win.
Width<string | number>
Placeholder width in pixels or a CSS length. Defaults to the available width and never exceeds the container.