Pricing

Progress handbook

v1.1.2 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Show task progress as a bar or circle, for measured progress or an indeterminate state during upload, processing, and loading.

When to use it

Use Progress for known or unknown completion. Set isIndeterminate when progress is unknown. Spinner can indicate waiting without a percentage; GaugeChart is for business metrics.

  • value is a percentage from 0 to 100. Use isIndeterminate when progress is unknown rather than inventing a percentage.

  • variant selects line or circle. For a circle, showLabel generates a label; explicit children replace the default label.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Button, Frame, Progress, Text } from '@snowui-design-system/components';	let progress = $state(38);	const status = $derived(progress === 100 ? 'Documentation ready' : 'Generating documentation');	function advance() { progress = Math.min(100, progress + 16); }</script> <div style="display: flex; flex-direction: column; align-items: stretch; gap: var(--gap-4); width: min(100%, 32rem); min-width: 0;">	<Progress value={progress} aria-label="Documentation generation progress">		<Frame as="label" singleLine style="justify-content: space-between;">			<Text lines={1}>{status}</Text>			<Text as="trailing" lines={1}>{progress}%</Text>		</Frame>	</Progress>	<div style="display: flex; justify-content: center; gap: var(--gap-2);">		<Button onclick={advance} disabled={progress === 100}>Advance</Button>		<Button onclick={() => progress = 0}>Reset</Button>	</div></div>

API

Keyword Type Default Description
value number 0 Percentage, automatically clamped to 0–100.
variant ProgressVariant "line" Bar or circle.
size number | string 16 Circle width and height; defaults match Spinner.
thickness number | string — Bar height or ring thickness. Circle and indeterminate states match Spinner ring width. Defaults: 4px for a determinate line; 15% of size for a circle or indeterminate state (2.4px at size 16).
background SnowUIColor | string "Black4" Track background color
color SnowUIColor | string "Primary" Fill color
isIndeterminate boolean false Indeterminate state
showLabel boolean false Circle only: in determinate mode, generate built-in Text showing the live value.
loopMotion LoopMotionConfig — Override indeterminate loop timing.
children Snippet — Explicit label composition; replaces the built-in circle label when present.
parts ComponentPartsOf<{ Text: typeof Text }> — Configure the built-in Text label for circle.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Layout model

Main layout model: managed composite layout.

  • variant="line": the explicit label is stacked above the bar with a default 4px gap and spans the available Progress width.

  • variant="circle": showLabel=true generates built-in Text centered over the SVG ring; it is hidden by default.

  • An empty direct child with as="label" displays the live value automatically; explicit label content stays unchanged.

  • Default label typography is 12px / 16px; external text, font size, and color can be customized.

  • A line has no built-in label. Its typical horizontal information area may contain a title, status, and percentage; one built-in string cannot determine that content or alignment.

Examples

<Progress value={60}>  <Frame as="label" singleLine class="justify-between">    <Text lines={1}>Loading</Text>    <Text as="trailing" lines={1}>60%</Text>  </Frame></Progress> <Progress variant="circle" value={50} size={32} showLabel /> <Progress value={60}>  <Text as="label">60%</Text></Progress>

Progress style overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

Variable Purpose and default reference
--snowui-progress-background-override Track background color (default var(--black-4))
--snowui-progress-color-override Fill color (default var(--primary))
--snowui-progress-gap-override Line label and track spacing (default var(--gap-1) = 4px)
--snowui-progress-thickness-override Line height / circle ring thickness (line definite state defaults 4px; circle / uncertain state default size × 15%)

Design Guide · Token · Combination Boundary

Progress type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: Omit<FrameProps, "children" | "size">. Consult the public Frame documentation; omitted fields cannot be passed through unchanged.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

ProgressVariant

Source: components/src/components/Progress.svelte

type ProgressVariant = "line" | "circle";

SnowUIColor

Source: components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

LoopMotionConfig

Source: components/src/logic/frame-types.ts

export interface LoopMotionConfig {    /** Loop preset (enables the full root Frame loop animation) */    preset?: LoopMotionPreset;    /** Loop duration (milliseconds) */    duration?: number;    /** Loop easing function */    easing?: MotionConfig["easing"];    /** Iteration count (default: infinite) */    iterationCount?: number | "infinite" | (string & {});    /** Direction (default: normal) */    direction?:        | "normal"        | "reverse"        | "alternate"        | "alternate-reverse";    /** Playback state (default: running) */    playState?: "running" | "paused";}

LoopMotionPreset

Source: components/src/logic/frame-types.ts

export type LoopMotionPreset = "rotateClockwise";

MotionConfig

Source: components/src/logic/motion-config.ts

export interface MotionConfig {    // === Transform properties ===    /** Scale (1 = 100%) */    scale?: number | [number, number];    /** Horizontal translation (px or a dimension string) */    x?: number | string | [number | string, number | string];    /** Vertical translation (px or a dimension string) */    y?: number | string | [number | string, number | string];    /** Rotation angle (degrees) */    rotate?: number | [number, number];    /** Y-axis rotation (degrees), for front/back flipping */    rotateY?: number | [number, number];    /** Opacity (0–1) */    opacity?: number | [number, number];    /** Blur radius (numeric values are px) */    blur?: number | string | [number | string, number | string];    /** Height (supports "+20px" relative syntax) */    height?: number | string;    /** Width */    width?: number | string;    /** Background color */    backgroundColor?: SnowUIColor | string;    /** Foreground/text/icon color for color transitions */    color?: SnowUIColor | string;     // === Timing parameters ===    /** Delay (milliseconds) */    delay?: number;    /** Duration (milliseconds) */    duration?: number;    /** Easing function */    easing?: EasingFunction;     // === Physics simulation ===    /** Motion type */    type?: 'spring' | 'tween';    /** Spring stiffness (higher is stiffer) */    stiffness?: number;    /** Spring damping (higher stops faster) */    damping?: number;    /** Spring mass */    mass?: number;    /** Spring velocity threshold (lower is stopped) */    velocity?: number;     // === Component reference ===    /** Use a custom component as the motion carrier (for example, FlowText or Spin) */    component?: any;     // === Orchestration control ===    /** Whether to participate in parent orchestration */    orchestrate?: boolean;}

EasingFunction

Source: components/src/logic/motion-config.ts

export type EasingFunction =    | 'linear'    | 'easeIn' | 'easeOut' | 'easeInOut'    | 'cubicIn' | 'cubicOut' | 'cubicInOut'    | 'quadIn' | 'quadOut' | 'quadInOut'    | 'quartIn' | 'quartOut' | 'quartInOut'    | 'quintIn' | 'quintOut' | 'quintInOut'    | 'sineIn' | 'sineOut' | 'sineInOut'    | 'expoIn' | 'expoOut' | 'expoInOut'    | 'circIn' | 'circOut' | 'circInOut'    | 'backIn' | 'backOut' | 'backInOut'    | 'elasticIn' | 'elasticOut' | 'elasticInOut'    | 'bounceIn' | 'bounceOut' | 'bounceInOut'    | (string & {});

ComponentPartsOf

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartsOf<    T extends Record<string, Component<any>>,> = {    [K in keyof T]?: ConfigurableComponentPartProps<T[K]>;};

ConfigurableComponentPartProps

Source: components/src/logic/component-parts.svelte.ts

export type ConfigurableComponentPartProps<C extends Component<any>> = Partial<    Omit<ComponentProps<C>, ComponentPartControlledKey>>;

ComponentPartControlledKey

Source: components/src/logic/component-parts.svelte.ts

export type ComponentPartControlledKey =    | "children"    | "as"    | "value"    | "defaultValue"    | "open"    | "selected"    | "checked"    | "disabled"    | "readonly"    | "id"    | `on${string}`    | `aria-${string}`;