@payfit/unity-components
Version:
91 lines (90 loc) • 4.57 kB
TypeScript
import { HTMLAttributes } from 'react';
/**
* Unity typography styles that `Skeleton` can mirror when `variant="text"`.
* Use the same style as the content that the placeholder will replace so its
* line height and vertical rhythm remain stable while data loads.
*/
export type SkeletonTextVariant = 'displayHeading' | 'h1' | 'h2' | 'h3' | 'h4' | 'overline' | 'subtitle' | 'displayTitle' | 'displayBody' | 'body' | 'bodyStrong' | 'bodySmall' | 'bodySmallStrong' | 'bodyLarge' | 'bodyLargeStrong' | 'action' | 'actionLarge' | 'actionSmall' | 'actionInfo';
type SkeletonBaseProps = Omit<HTMLAttributes<HTMLDivElement>, 'aria-hidden'> & {
'aria-hidden'?: boolean;
};
/**
* Props for {@link Skeleton}.
* Set `variant="text"` to expose the optional `textVariant` prop. Rectangular
* and circular placeholders intentionally reject `textVariant` so consumers
* cannot accidentally apply typography styles to non-text shapes.
* @property variant - Selects `rectangular`, `circular`, or `text`; defaults to
* `rectangular`.
* @property textVariant - Selects the Unity typography style for a text
* skeleton. It has an effect only when `variant="text"`.
* @property className - Adds layout and sizing classes. Use `uy:w-*` and
* `uy:h-*` for rectangular placeholders, `uy:size-*` for circular
* placeholders, and `ch`-based width classes such as `uy:w-[24ch]` for text.
* @property aria-hidden - Hides the placeholder from assistive technologies;
* defaults to `true` because the shape is normally decorative.
* @see {@link SkeletonTextVariant} for the available text styles.
*/
export type SkeletonProps = SkeletonBaseProps & ({
variant?: 'rectangular' | 'circular';
textVariant?: never;
} | {
variant: 'text';
textVariant?: SkeletonTextVariant;
});
/**
* Reserves the shape and rhythm of content while its data loads.
* Use `Skeleton` inside a stable layout when the final content dimensions are
* known but the content itself is not available yet. Choose a shape with
* `variant`, mirror text with `textVariant`, and pass explicit Unity sizing
* classes through `className`.
* @param props - Placeholder content, shape, typography, sizing, and HTML
* attributes.
* @param props.variant - Selects the placeholder shape. It defaults to
* `"rectangular"`; use `"circular"` for avatar-like content and `"text"` for
* typography-shaped content.
* @param props.textVariant - Selects the Unity typography style when
* `variant="text"`, such as `"h2"`, `"body"`, or `"bodySmallStrong"`.
* @param props.className - Supplies the dimensions and layout. Use
* `uy:w-*`/`uy:h-*` for rectangular shapes, `uy:size-*` for circular shapes,
* and `uy:w-[##ch]` for text widths that approximate the expected copy.
* `Skeleton` merges these classes with its generated visual styles so the
* variant's neutral background, animation, and shape treatment remain intact.
* @param props.aria-hidden - Defaults to `true` and keeps the decorative
* placeholder out of the accessibility tree. Set it to `false` only when the
* placeholder itself conveys information that users of assistive technology
* need to receive.
* @example
* ```tsx
* import { Skeleton } from '@payfit/unity-components'
*
* export function EmployeeCard({ isLoading }: { isLoading: boolean }) {
* return (
* <section aria-busy={isLoading} aria-label="Employee profile">
* {isLoading ? (
* <>
* <Skeleton variant="circular" className="uy:size-600" />
* <Skeleton
* variant="text"
* textVariant="h2"
* className="uy:w-[18ch]"
* />
* </>
* ) : (
* <h2>Ada Lovelace</h2>
* )}
* </section>
* )
* }
* ```
* @remarks
* Keep `Skeleton` itself decorative and expose loading semantics on the
* containing region with `aria-busy` and an accessible label. The component
* renders a `div` and forwards standard `HTMLAttributes<HTMLDivElement>` and
* its ref, so it does not provide interactive behavior or focus management.
* @see {@link SkeletonProps} for the complete prop contract.
* @see {@link SkeletonTextVariant} for text style values.
* @see [Figma component design](https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library?node-id=22530-2318)
* @see [Zeroheight Skeleton documentation](https://www.payfit.design/24f360409/v/latest/p/87f013)
*/
export declare const Skeleton: import('react').ForwardRefExoticComponent<SkeletonProps & import('react').RefAttributes<HTMLDivElement>>;
export {};