Progress

Feedback component. This page is the API reference, generated from the source code. Usage guidance and live examples are on the Chinese page.

HeadlessStylesVueReactWeb Components

Anatomy

Parts in bold are required.

data-scope="progress": root · canvas · track · range · buffer · label · threshold · target · scale · scale-tick · scale-label · needle

API reference

Descriptions of individual props, events and slots are written in Chinese and appear on the Chinese page.

Artifacts

Layer	Value
Custom element	<xh-progress>
Vue components	XhProgress
State machine	None: connect computes attributes from props directly
Skin	@xihan-ui/styles/progress.css

Props

Prop	Type	Required
buffer	number
gapDegree	number
gapPosition	ProgressGapPosition
indeterminate	boolean
indicator	ProgressIndicator
locale	string
max	number
scale	boolean | ProgressScaleOptions
semantics	ProgressSemantics
size	Size
steps	number
striped	boolean
strokeWidth	number
target	number
thresholds	readonly ProgressThreshold[]
tone	Tone
translations	Partial<ProgressTranslations>
value	number
valueText	string
variant	ProgressVariant

ProgressThreshold

Elements of thresholds.

Field	Type	Required
value	number	Yes
tone	Tone	Yes
label	string

State

Public state is written to data-state.

Part	Values
root	'indeterminate' | 'complete' | 'loading'
label	'complete' | 'loading'

connect API

getXxxProps() returns the host attributes of the matching part.

Member	Type
variant	ProgressVariant
semantics	ProgressSemantics
ratio	number
percent	number
steps	number
buffer	number | null
getRootProps	() => T['element']
getCanvasProps	() => T['element']
getTrackProps	() => T['element']
getRangeProps	() => T['element']
getBufferProps	() => T['element']
getLabelProps	() => T['element']
bands	readonly ProgressBand[]
ticks	readonly ProgressTick[]
target	number | null
indicator	ProgressIndicator
getThresholdProps	(band: ProgressBand) => T['element']
getTargetProps	() => T['element']
getScaleProps	() => T['element']
getScaleTickProps	(tick: ProgressTick) => T['element']
getScaleLabelProps	(tick: ProgressTick) => T['element']
getNeedleProps	() => T['element']

Accessibility

Keyboard

Specification: W3C APG. Each row is a stable behavior id that the conformance tests cover; the conditions and effects are described on the Chinese page.

No keyboard interaction: the component takes no focus, or focus behavior comes entirely from native elements.

ARIA

These attributes are produced by connect.

Part	Attribute	Value
root	aria-valuemax	String(max)
root	aria-valuemin	'0'
root	aria-valuenow	undefined | String(value)
root	aria-valuetext	props.valueText
root	role	'meter' | 'progressbar'
canvas	aria-hidden	'true'
scale	aria-hidden	'true'

Style reference

Skin

@xihan-ui/styles/progress.css is written against [data-scope="progress"][data-part="root"] part selectors; the published build uses the mount class .xh-scope-progress in place of data-scope (same specificity) and sits in the xihan.components and xihan.motion layers. Put overrides in xihan.overrides; the part selectors work as usual.

Data attributes

Produced by connect; valueless attributes are omitted while their condition does not hold.

Part	Attribute	Value
root	data-banded	'' (present only while the condition holds)
root	data-indicator	'needle' | undefined
root	data-size	props.size
root	data-state	'indeterminate' | 'complete' | 'loading'
root	data-tone	props.tone
root	data-variant	props.variant
canvas	data-variant	props.variant
track	data-stepped	'' (present only while the condition holds)
range	data-empty	'' (present only while the condition holds)
range	data-indicator	'needle' | undefined
range	data-striped	'' (present only while the condition holds)
range	data-tone	active?.tone
buffer	data-tone	props.tone
buffer	data-variant	props.variant
label	data-indicator	'needle' | undefined
label	data-state	'complete' | 'loading'
label	data-variant	props.variant
threshold	data-tone	band.tone
threshold	data-variant	props.variant
target	data-variant	props.variant
scale	data-variant	props.variant
scale-tick	data-variant	props.variant
scale-label	data-variant	props.variant

CSS variables

The public override slots, generated from what the standalone skin actually consumes.

Variable	Part	CSS property	State	Default from
--xh-progress-buffer	buffer	background	default	--xh-_tone-subtle-active
--xh-progress-buffer-radius	buffer	border-radius	default	--xh-progress-range-radius
--xh-progress-indeterminate-duration	range	animation	state=indeterminate	--xh-motion-loop-shimmer
--xh-progress-label-fg	label	color	default	--xh-fg-muted
--xh-progress-label-font-size	label	font-size	default	--xh-text-caption-size
--xh-progress-linecap	range	stroke-linecap	variant=circle variant=dashboard	round
--xh-progress-needle-color	needle	fill	default	--xh-fg-default
--xh-progress-range	range	background stroke	default variant=circle variant=dashboard	--xh-_tone
--xh-progress-range-radius	buffer range	border-radius	default	--xh-shape-pill
--xh-progress-size	root	block-size inline-size	size=lg size=sm variant=circle variant=dashboard	10rem 5rem 7.5rem
--xh-progress-step-gap	track	-webkit-mask-image mask-image	stepped	--xh-space-0_5
--xh-progress-stripe-color	range	background-image	striped	--xh-_tone-active
--xh-progress-stripe-duration	range	animation	state=loading striped	--xh-motion-loop-shimmer
--xh-progress-stripe-size	range	background-position background-size	@keyframes xh-progress-stripes striped	--xh-space-4
--xh-progress-target-color	target	background stroke	variant=circle variant=dashboard variant=line	--xh-fg-default
--xh-progress-target-radius	target	border-radius	variant=line	--xh-shape-pill
--xh-progress-thickness	root target track	block-size	banded default size=lg size=sm variant=line	--xh-track-band-thickness-lg --xh-track-band-thickness-md --xh-track-band-thickness-sm --xh-track-thickness-lg --xh-track-thickness-md --xh-track-thickness-sm
--xh-progress-threshold-color	threshold	background stroke	variant=circle variant=dashboard variant=line	--xh-_tone-subtle-active
--xh-progress-track	track	background stroke	default variant=circle variant=dashboard	--xh-bg-subtle-hover
--xh-progress-track-radius	track	border-radius	default	--xh-shape-pill