FloatButton

General 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="float-button": root · trigger · list

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-float-button>
Vue components	XhFloatButtonList XhFloatButtonRoot XhFloatButtonTrigger
Composable	useFloatButton
State machine	floatButtonMachine
Skin	@xihan-ui/styles/float-button.css

Props

Prop	Type	Required
defaultOpen	boolean
defaultPosition	FloatButtonPosition
dir	Direction
disabled	boolean
draggable	boolean
expandTrigger	FloatButtonExpandTrigger
offset	number
onOpenChange	(details: CollapsibleOpenChangeDetails) => void
onPositionChange	(details: FloatButtonPositionChangeDetails) => void
open	boolean
placement	FloatButtonPlacement
position	FloatButtonPosition
size	Size
snap	FloatButtonSnap
tone	Tone
translations	Partial<FloatButtonTranslations>
variant	ActionVariant

Events

Custom elements put the payload in detail; Vue emits an event of the same name.

Event	Payload
open-change	CollapsibleOpenChangeDetails
position-change	FloatButtonPositionChangeDetails

Slots

Only slots with a payload are listed.

Vue component	Slot	Payload
XhFloatButtonRoot	default	FloatButtonRootSlotProps

React adapter props

Only the props each component declares itself: DOM attributes inherited from ComponentPropsWithRef are left out, and root props already listed in the Props table are not repeated. The Vue counterpart is the slot table above.

React component	Prop	Type	Required
XhFloatButtonRoot	children	SlotChildren<FloatButtonRootSlotProps>

State

Public state is written to data-state.

Part	Values
root	'open' | 'closed'
trigger	'open' | 'closed'
list	'open' | 'closed'

The following names are internal to the state machine.

States: open · closed

Events: OPEN · CLOSE · TOGGLE · DISABLE · CONTROLLED.OPEN · CONTROLLED.CLOSE · PRESS.START · PRESS.END · DRAG.START · DRAG.MOVE · DRAG.END · CLICK.SWALLOW · VIEWPORT.RESIZE

Guards: isDisabled · isOpenControlled · canPress · canDrag

connect API

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

Member	Type
open	boolean
setOpen	(next: boolean) => void
position	FloatButtonPosition | null
setPosition	(next: FloatButtonPosition) => void
dragging	boolean
getRootProps	() => T['element']
getTriggerProps	() => T['button']
getListProps	() => 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.

Keys	Behavior
Enter / Space	float-button.kbd.toggle
Enter / Space	float-button.kbd.press
Escape	float-button.kbd.escape
Tab / Shift+Tab	float-button.kbd.tab

ARIA

These attributes are produced by connect.

Part	Attribute	Value
trigger	aria-controls	id of the list part
trigger	aria-expanded	'true' | 'false'
trigger	aria-label	translations.trigger
list	aria-labelledby	id of the trigger part
list	role	'group'

Style reference

Skin

@xihan-ui/styles/float-button.css is written against [data-scope="float-button"][data-part="root"] part selectors; the published build uses the mount class .xh-scope-float-button in place of data-scope (same specificity) and sits in the xihan.components layer. 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-disabled	'' (present only while the condition holds)
root	data-draggable	'' (present only while the condition holds)
root	data-dragging	'' (present only while the condition holds)
root	data-edge	edge?.edge
root	data-moving	'' (present only while the condition holds)
root	data-placement	floatButtonPlacementOf(position, context.get('viewpor… | props.placement
root	data-point	'' (present only while the condition holds)
root	data-size	props.size
root	data-state	'open' | 'closed'
root	data-tone	props.tone
root	data-variant	props.variant
trigger	data-disabled	'' (present only while the condition holds)
trigger	data-pressed	'' (present only while the condition holds)
trigger	data-state	'open' | 'closed'
trigger	data-xh-action-control	''
trigger	data-xh-action-display	'always'
trigger	data-xh-action-profile	'floating'
trigger	data-xh-action-size	props.size
trigger	data-xh-action-variant	props.variant
trigger	data-xh-ink-surface	'' (present only while the condition holds)
trigger	data-xh-liquid	''
trigger	data-xh-material	'frosted' | undefined
list	data-instant	'' (present only while the condition holds)
list	data-placement	floatButtonPlacementOf(position, context.get('viewpor… | props.placement
list	data-state	'open' | 'closed'

CSS variables

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

Variable	Part	CSS property	State	Default from
--xh-float-button-bg	list root trigger	--xh-ink-surface background-color	default disabled focus-visible not([data-scope]) variant=outline variant=subtle xh-ink-surface	--xh-_action-variant-bg-disabled --xh-_action-variant-bg-focus-visible --xh-_action-variant-bg-rest --xh-_float-button-bg --xh-_material-bg --xh-_material-bg-focus
--xh-float-button-bg-active	list root trigger	background-color	active disabled is(:active, [data-pressed]) loading not(:disabled) not([data-disabled]) not([data-loading]) not([data-scope]) pressed variant=outline variant=subtle	--xh-_action-variant-bg-pressed --xh-_float-button-bg-active --xh-_material-bg-pressed
--xh-float-button-bg-hover	list root trigger	background-color	@media (hover: hover) disabled hover loading not(:disabled) not([data-disabled]) not([data-loading]) not([data-scope]) variant=outline variant=subtle	--xh-_action-variant-bg-hover --xh-_float-button-bg-hover --xh-_material-bg-hover
--xh-float-button-border	list root trigger	border border-color	default disabled focus-visible not([data-scope]) variant=outline	--xh-_action-variant-border-disabled --xh-_action-variant-border-focus-visible --xh-_action-variant-border-rest --xh-_float-button-border --xh-_material-border
--xh-float-button-border-hover	list root trigger	border-color	@media (hover: hover) disabled hover is(:active, [data-pressed]) loading not(:disabled) not([data-disabled]) not([data-loading]) not([data-scope]) pressed variant=outline	--xh-_action-variant-border-hover --xh-_action-variant-border-pressed --xh-_float-button-border-hover --xh-_material-border
--xh-float-button-fg	list root trigger	color	default disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) not([data-scope]) pressed variant=outline	--xh-_action-variant-fg-focus-visible --xh-_action-variant-fg-hover --xh-_action-variant-fg-pressed --xh-_action-variant-fg-rest --xh-_float-button-fg --xh-_material-fg
--xh-float-button-gap	list root	gap	default	--xh-space-2
--xh-float-button-icon-size	root trigger	--xh-icon-size	default	--xh-_float-button-glyph-size
--xh-float-button-layer	root	z-index	default	--xh-_layer
--xh-float-button-radius	list trigger	border-radius	default	--xh-_action-profile-radius --xh-shape-circle
--xh-float-button-shadow	list root trigger	box-shadow	default disabled focus-visible hover is(:active, [data-pressed]) is(:hover, [data-loading]) loading not([data-disabled]) not([data-loading]) not([data-scope]) pressed variant=outline	--xh-_float-button-shadow --xh-_material-shadow none
--xh-float-button-size	list root trigger	block-size bottom inline-size inset-block-end inset-block-start inset-inline-end inset-inline-start left min-inline-size top	default edge=block edge=inline moving placement placement=-end placement=-start placement=bottom placement=top point xh-action-profile=floating	--xh-_float-button-size