Streaming animation reveals multiple markdown sections concurrently instead of serializing section animation

[ryanyue123]

Bug Description

Streamed markdown can animate multiple sections at once.

For example, while a list is still animating in, the next paragraph or heading can already start animating too. The content order is correct, but the visual reveal feels wrong because multiple sections are “live” at the same time.

Steps to Reproduce

1. Stream structured markdown with multiple sections, for example:

• a paragraph
• a short intro line
• a bullet list
• a closing paragraph

2. Watch the response while it is still streaming.
3. Notice that the next paragraph or heading begins animating before the earlier list or section has visually finished.

Expected Behavior

The list finishes animating before the next paragraph

Actual Behavior

Code Sample

Streamdown Version

2.5.0

React Version

19.2.2

Node.js Version

No response

Browser(s)

No response

Operating System

None

Additional Context

No response

[awbalessa]

Hey @ryanyue123, facing the exact same issue on my end. Did you find out more about why this is happening, or how we can mitigate?

[ryanyue123]

Hey @ryanyue123, facing the exact same issue on my end. Did you find out more about why this is happening, or how we can mitigate?

i dont think streamdown has inter-block stagger coordination. basically when markdown is streaming in a new block can stream in while the previous block's animation is still finishing up, causing it to look like its streaming the blocks in "parallel".

I think this can happen with any blocks but may be exaggerated with lists? (not too sure).

here's what claude said when I asked about the actual flow:

1. Chunks 3-6: List items stream in. Each new - item\n chunk
   causes the list block to re-render. The animate plugin tracks
   prevContentLength to skip already-visible characters, only
   animating new list items with stagger delays starting from
   newIndex = 0 within that render pass.
2. Chunk 7 (- Select vendor...\n\n): The trailing \n\n
   completes the list block. New list item animates in with stagger.
3. Chunk 8 (closing paragraph): A new block appears in the blocks
   array. The list block is now memoized (content unchanged) so it
   doesn't re-render. But the new paragraph block renders with:
   - prevContentLength = 0 (it's new, no prior content to skip)
   - newIndex starting at 0 → stagger delays: 0ms, 40ms, 80ms,
   120ms...
4. Visual result: The list block's last batch of words still has
   CSS animations playing out (e.g., word 5 at delay 200ms hasn't
   finished its 150ms animation yet = 350ms total). The paragraph's
   words start fading in from 0ms simultaneously.

[cadenmarinozzi]

Also noticing this from 2.5.0. This seems to be a new problem stemming from my issue opened from a few weeks ago: #437. Even without markdown or rich content, animation causes text with line breaks to animate in parallel if the content is received quickly.

[Doge-is-Dope]

This exact issue was already reported on the day 2.5.0 was released, but it doesn’t appear to be fixed yet.

[ernieturner]

You can get around this by reverting the stagger option that was added in ac8d839 back to 0. That option (which defaults to 40ms) seems to be the cause here. Which is a shame because the animation is way smoother this way, but the out-of-order rendering is pretty visually overwhelming.

const animation = {
  animation: 'fadeIn',
  duration: 150,
  easing: 'ease',
  stagger: 0,
}

<Streamdown isAnimating animated={animation}> ...</Streamdown>

[dergachoff]

This is a very annoying issue, bumping

[chrisjpatty]

I spent about four hours trying to figure out what the hell was going wrong with my code that everything was streaming concurrently before I found this issue.

[fmhall]

Would also love to see this fixed!

[doneumark]

+1 !

[stefantrajanov]

Extremely annoying issue really

[LingChen-tsjmdlc]

I hope to merge branches as soon as possible！
I think this issue is still quite serious, and I also like this repo instead of the react-markdown repo because of this animation function.

[aradhyacp]

For anyone wondering about the lack of activity: the original lead maintainer, @haydenbleasel, moved to OpenAI a few months ago. Since then, there has been very little maintainer activity on this repository, and many issues and PRs appear to be awaiting review.

We haven't seen an official update on the project's maintenance status, but that may explain why issues have been piling up without much response. So it would be great if someone from Vercel could clarify about this project.