<template>
<TxStagger tag="ul" name="tx-stagger" :delay-base="40" :delay-step="24">
<li v-for="notification in notifications" :key="notification.id">
{{ notification.title }}
</li>
</TxStagger>
</template>
<template>
<TxStagger name="fade-list" :duration="240" easing="linear">
<article v-for="card in cards" :key="card.id">
{{ card.title }}
</article>
</TxStagger>
</template>
.fade-list-enter-active,
.fade-list-leave-active {
transition: opacity 240ms linear;
transition-delay: calc(var(--tx-stagger-index) * 24ms);
}
- Always provide stable keys for children. Staggered transitions without stable keys are unpredictable.
- Keep
delayStep small for long lists; large delays make later items feel broken. - Use
tag="ul" / li for semantic lists instead of styling a generic div as a list. - Avoid wrapping virtualized rows with
TxStagger; virtual list DOM churn and staggered transitions fight each other. - Use a custom
name only when you also provide matching transition CSS.
| Prop | Type | Default | Description |
|---|
tag | string | 'div' | Root tag passed to TransitionGroup. |
appear | boolean | true | Whether the appear transition runs; passed to TransitionGroup from the first render. |
name | string | 'tx-stagger' | TransitionGroup class-name prefix; effective from the first render. |
duration | number | 180 | Enter and leave transition duration in milliseconds. |
delayStep | number | 24 | Extra delay per rendered child index, in milliseconds. |
delayBase | number | 0 | Base delay before index-based delay, in milliseconds. |
easing | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'linear' | 'ease-out' | CSS timing function used by built-in transitions. |
| Event | Payload | Description |
|---|
| - | - | TxStagger does not emit custom events. Transition lifecycle is provided by Vue TransitionGroup classes, not component emits. |
| Slot | Props | Description |
|---|
default | - | Keyed child VNodes rendered by TransitionGroup. |
| Variable | Source | Description |
|---|
--tx-stagger-index | child index | Per-child index used for delay calculation. |
--tx-stagger-duration | duration | Transition duration. |
--tx-stagger-delay-step | delayStep | Delay multiplier per child. |
--tx-stagger-delay-base | delayBase | Base delay. |
--tx-stagger-easing | easing | Timing function. |
- The component renders Vue
TransitionGroup with class tx-stagger and root tag from tag. - Default slot VNodes are filtered to remove comment nodes before index assignment.
- Each rendered child is cloned with its existing style plus
--tx-stagger-index: <index>. - Timing props are written on the root as
--tx-stagger-duration, --tx-stagger-delay-step, --tx-stagger-delay-base, and --tx-stagger-easing. - Built-in CSS uses opacity and
translateY(6px) for enter/leave transitions. name and appear are passed to TransitionGroup on the first render — TransitionGroup only runs its appear transition on initial mount and consumes both as props (not fallthrough attrs), so deferring them would permanently skip appear.- Child nodes must have stable Vue keys for
TransitionGroup move/enter/leave behavior. - Existing child inline styles are preserved when the stagger index style is added.
- Reviewed against
packages/tuffex/packages/components/src/stagger/src/TxStagger.vue, types.ts, and stagger.test.ts. - Existing tests cover root tag passthrough, slot rendering, timing CSS variables, transition prop leakage prevention, comment filtering, and child stagger index assignment.
- Rendering note:
name and appear are supplied as TransitionGroup props from the first render, so the initial-mount appear transition runs as expected. - Accessibility note:
TxStagger adds no semantic role. Choose tag and child elements that preserve list, grid, or feed semantics before styling transitions. - Component source:
packages/tuffex/packages/components/src/stagger/src/TxStagger.vue. - Types:
packages/tuffex/packages/components/src/stagger/src/types.ts exports StaggerProps and StaggerEasing. - Verified coverage:
packages/tuffex/packages/components/src/stagger/__tests__/stagger.test.ts covers root-tag passthrough and slot rendering, timing CSS variables, transition-prop leakage prevention, comment filtering, and child stagger-index assignment.查看源码packages/tuffex/packages/components/src/stagger/index.ts