Components/MotionControl

MotionControl

A set of animated controls ported from the Amicro UIkit.

VerifiedSince 0.7.0

Usage

All Variants

variant picks the control; the caller supplies every option and command.

Loading demo...

Best Practices

  • Keep business results in the application: a menu command is not a backend success, a PiP state is not a platform switch, and download is only a request.
  • Use stable value keys and localize labels separately; supply categories, dates, frequencies, tabs, and commands yourself.
  • Bind both v-model and v-model:items for closeable tabs. Set minItems="1" to keep the last tab, and allocate real IDs from add.
  • Keep the item slot non-interactive; put independent actions outside the native buttons and rich content in the panel slot.
  • Drive status and progress from the real transfer, and handle cancellation and errors there.

API Reference

Props

PropTypeDefaultMeaning
variantMotionControlVariantyui-category-selectOne of 34 variants; the 21 catalog IDs match upstream.
modelValuestring | number | booleanVariant-dependentControlled value. Without it, state stays local and selections default to the first enabled choice.
optionsMotionControlItem[][]Choices for selection variants; win over items, but closeable tabs read only items.
itemsMotionControlItem[][]Menu commands or closeable tabs, bound with v-model:items.
countnumber3 for step bar/stepper, otherwise 4Segments, pages, or generated steps when there are no options.
minnumber0Counter minimum; also the uncontrolled starting value.
maxnumber—Counter maximum.
stepnumber1Counter and radial-progress increment; 25 gives the source's quarter steps.
disabledbooleanfalseBlocks selection, commands, value changes, closing, adding, and download requests.
sizexs | sm | md | lgmdControl height and inset.
statusidle | loading | success | erroridleHost-owned download state; loading blocks repeats, and only success shows the check.
progressnumber0Host-owned download percentage, shown while loading.
openboolean—Controlled menu, tooltip, or frequency expansion; the category select ignores it.
animatedbooleantrueEnables motion; it still stops offscreen, when hidden, or under reduced motion.
labelstring''Visible label, or the group or trigger's accessible name, depending on the variant.
tooltipstring''Tooltip or glance text; the hover link falls back to href.
hrefstring''Hover-link destination; without it, the trigger is a button that emits action.
target_self | _blank_selfLink target; _blank adds noopener noreferrer.
newItemMotionControlItem—A tab the caller prepared; duplicate values are not added.
maxItemsnumber—Maximum tab count.
minItemsnumber0Tabs that must remain; 1 matches upstream's undeletable last tab.
canBackbooleantrueAllows the back request.
canForwardbooleantrueAllows the forward request.
labelsPartial<MotionControlLabels>English labelsOverrides default strings without a library message catalog.

Events

EventPayloadWhen
update:modelValueMotionControlValueA permitted operation changes the value.
changeMotionControlValueWith update:modelValue; not for an unchanged value.
selectMotionControlItemAn option, step, tab, or command is chosen, including a repeat.
update:itemsMotionControlItem[]A tab closes or newItem is added.
update:openbooleanA menu, tooltip, or frequency expansion changes.
closeMotionControlItemA tab closes.
addMotionControlItem | undefinednewItem is added, or, without one, the host is asked to create a tab.
action{ variant, value, item? }An action, link, hint, toggle, menu command, or frequency confirmation runs.
navigate'back' | 'forward'A permitted back or forward request; browser history is untouched.
download—A download request for the application; not a completion event.

Slots

SlotScopePurpose
default—Label of the hover link, magnetic button, or morph button.
item{ item, active }Tab and step content; keep it non-interactive.
icon{ item, active }Tab icon; renders only for items with icon set.
panel{ item, active? }Content for a tab; reserves no space when omitted.
menu{ items, select }Replaces the menu content; call select(item) to emit the command.
preview—Tooltip or glance preview content.
value{ value, item }Host-rendered value, count, or selection beside the control.

Types

MotionControlItem

FieldTypeDescription
valuestring | numberUnique key, also after string conversion.
labelstringDisplay text.
disabledbooleanDisables the item.
iconstringText glyph; use the icon slot for SVG or components.
descriptionstringDescription, passed to TxSelect.
closablebooleanfalse makes the tab uncloseable.
dangerbooleanDestructive command style.
childrenMotionControlItem[]Submenu, rendered recursively as dropdown or context submenus.

MotionControlLabels

Keys and defaults of labels, exported as MOTION_CONTROL_DEFAULT_LABELS:

{
  control: 'Motion control', choose: 'Choose an option', frequency: 'Frequency',
  confirm: 'Confirm selection', add: 'Add tab', close: 'Close',
  increase: 'Increase', decrease: 'Decrease', back: 'Back', forward: 'Forward',
  actions: 'Actions', details: 'View details', action: 'Action', launch: 'Launch',
  link: 'Open link', preview: 'Preview', help: 'Help', download: 'Download',
  downloading: 'Downloading', downloaded: 'Downloaded', downloadError: 'Download failed',
  pip: 'Enter picture in picture', pipOff: 'Exit picture in picture',
  save: 'Save item', saved: 'Saved', follow: 'Follow', following: 'Following',
  grid: 'Grid view', list: 'List view', stack: 'Stack view', light: 'Light mode',
  dark: 'Dark mode', progress: 'Progress', page: 'Page',
}

Source Mapping

Paths are relative to upstream src/components/css-animations/. MOTION_CONTROL_SOURCES exports each entry's full path, line range, upstream export, and model domain; MOTION_CONTROL_VARIANTS exports every variant ID.

Catalog Variants

VariantUpstream exportSourceStructure and model
yui-category-selectCategorySelectyui-components/YuiUiKit1.tsx:9–63Rounded select with dropdown menu; option key.
yui-filter-tag-pillFilterTagPillyui-components/UiKitTrios.tsx:10–38Segmented filter with travelling pill; option key.
yui-submenu-flyoutSubmenuFlyoutyui-components/UiKitTrios.tsx:41–74Sideways submenu flyout; commands.
yui-hover-linkHoverLinkCardyui-components/YuiUiKit1.tsx:66–107Lifted link pill with floating URL; href or action.
yui-magnetic-icon-btnMagneticIconButtonyui-components/UiKitTrios.tsx:81–94Arrow button with horizontal travel; action.
yui-morph-action-pillMorphActionPillyui-components/UiKitTrios.tsx:97–124Pill that expands on hover or focus; action.
yui-plus-minus-togglePlusMinusToggleyui-components/YuiUiKit1.tsx:110–142Two square buttons with press bounce; plus / minus.
yui-light-dark-toggleLightDarkMorphToggleyui-components/YuiUiKit1.tsx:145–169Sun/moon rotation; boolean.
yui-ab-tabsSegmentedABTabsyui-components/YuiUiKit2.tsx:202–238Wide segmented tabs with sliding pill; A/B choices.
yui-progress-stepperProgressStepperyui-components/YuiUiKit1.tsx:172–216Connected steps with filled track; option key or one-based step.
yui-segmented-arc-meterSegmentedArcMeteryui-components/RedesignedUiTrios.tsx:10–30Discrete bars with percentage; 0..count.
yui-segmented-step-barSegmentedStepBaryui-components/UiKitTrios.tsx:159–174Battery segments; click cycles the level.
yui-multi-tab-closeMultiTabCloseBaryui-components/YuiUiKit1.tsx:219–287Closeable tabs, shrink/fade exits, add request; selection and items.
yui-date-positionDatePositionSelectoryui-components/YuiUiKit1.tsx:290–328Consecutive dates with sliding highlight; option key.
yui-stepper-dotsSegmentedStepperDotsyui-components/RedesignedUiTrios.tsx:35–61Active dot expands to a pill; one-based page.
yui-context-menuContextMenuEditDeleteyui-components/YuiUiKit2.tsx:9–56Scale/fade action popup; edit/delete or supplied commands.
yui-glance-previewCardGlancePreviewyui-components/RedesignedUiTrios.tsx:66–100Floating preview with status dot; hover/focus.
yui-download-iconsDownloadAnimatedIconsyui-components/YuiUiKit2.tsx:99–138Bouncing arrow while loading; check on success.
yui-wheel-counterVerticalWheelCounteryui-components/RedesignedUiTrios.tsx:105–143Vertical number morph with up/down buttons; bounded number.
yui-perspective-layoutPerspectiveLayoutSwitcheryui-components/RedesignedUiTrios.tsx:148–170Grid/stack icons rotate and scale in; grid / stack.
yui-save-pillBookmarkSavePillyui-components/RedesignedUiTrios.tsx:175–193Bookmark/check pill with changing label; boolean.

Additional Exports

VariantUpstream exportSourceStructure and model
frequency-selectorFrequencySelectorFrequencySelector.tsx:12–126Blurred label, option pills, and a confirm button.
tab-barTabBarTabBar.tsx:16–72Icon tabs whose active label expands; option key.
radial-progress-ringRadialProgressRingyui-components/UiKitTrios.tsx:131–156SVG ring with percentage; click advances by step.
pagination-numbered-bubblePaginationNumberedBubbleyui-components/YuiUiKit1.tsx:331–366Active page bubble lifts; one-based page.
back-forward-navBackForwardNavyui-components/YuiUiKit1.tsx:369–397Two direction buttons; navigate.
question-tooltipQuestionTooltipyui-components/YuiUiKit2.tsx:59–97Round question trigger with anchored hint; hover/focus.
pip-mode-iconsPipModeIconsyui-components/YuiUiKit2.tsx:141–168Layer icon with entering mini-window; boolean and action.
simple-plus-minus-btnSimplePlusMinusBtnyui-components/YuiUiKit2.tsx:171–199Two small buttons without a display; bounded count.
quantity-counterQuantityCounteryui-components/YuiUiKit2.tsx:241–274Round pill with minus, animated number, and plus.
list-column-toggleListColumnToggleyui-components/YuiUiKit2.tsx:277–301Grid/list icon rotation with changing label; grid / list.
follow-check-buttonFollowCheckButtonyui-components/YuiUiKit2.tsx:304–322Plus/check follow pill; boolean.
menu-dots-expandMenuDotsExpandyui-components/YuiUiKit2.tsx:325–347Dots trigger that opens supplied commands.
compact-mode-switchCompactModeSwitchyui-components/YuiUiKit2.tsx:350–386Icon-only grid/list segments with active pill.

Overview

  • Composes TxSelect, TxTabs, TxDropdownMenu, TxContextMenu, TxTooltip, TxPagination, and TxTextMorph; focus, arrow keys, Escape, outside clicks, and anchoring follow those primitives.
  • On a focused counter, Up/Down step the value and Home/End jump to the bounds. The frequency selector returns focus to its trigger when it collapses.
  • In yui-multi-tab-close, closing the active tab selects the nearest enabled tab; closing another tab keeps the selection. Model events don't wait for the exit animation.
  • Close buttons sit in a separate strip beside the tab navigation, never inside a tab button.
  • Menu commands keep the primitives' select timing: a confirmation beat before closing, or immediate under reduced motion.
  • Motion stops offscreen, in hidden documents, in inactive KeepAlive instances, on unmount, and under reduced motion.

Technologies

  • Upstream: Amicro commit 43c29ce, MIT, Copyright (c) 2026 SYED SUBHAN UDDIN.
  • Source: packages/tuffex/packages/components/src/motion-control/.
查看源码
packages/tuffex/packages/components/src/motion-control/index.ts