hooks·hook·@astryxdesign/core

useStreamingText

Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.

Open in Playground @astryxdesign/core/hooks

Signature

Call shape

useStreamingText(targetText: string, isStreaming: boolean, options?: UseStreamingTextOptions): string

Parameters

Name	Type and behavior
`targetText`	`string` · required The full target text to reveal. As new chunks arrive, update this value with the accumulated text.
`isStreaming`	`boolean` · required Whether text is currently being streamed. When false, the hook returns the full targetText immediately.
`options`	`UseStreamingTextOptions` · optional Optional configuration for streaming behavior.
`options.speed`	`'natural' \| 'fast' \| 'instant'` · optional · default 'natural' Speed preset for text reveal. 'natural' is steady ~2 chars/frame, 'fast' scales with backlog ~4 chars/frame, 'instant' returns full text with no animation.

Returns

Name	Type and behavior
`displayedText`	`string` The portion of targetText to render. Grows steadily toward the full targetText during streaming, or equals targetText when not streaming.

Showcases and examples

1 documented example

useStreamingText — Streaming Response

Smooth bursty generated text into a steady reveal with useStreamingText.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · use-streaming-text-hook-usage

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useStreamingText} from '@astryxdesign/core/hooks';
import {Card} from '@astryxdesign/core/Card';
import {VStack} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';

const response =
  'Astryx hooks keep behavior reusable while components keep visuals consistent.';

export default function UseStreamingTextHookUsage() {
  const displayedText = useStreamingText(response, false, {
    speed: 'fast',
  });

  return (
    <Card width={420} padding={4}>
      <VStack gap={2}>
        <Text type="body" weight="bold">
          Assistant response
        </Text>
        <Text type="body">{displayedText}</Text>
        <Text type="supporting" color="secondary">
          Complete
        </Text>
      </VStack>
    </Card>
  );
}

Usage

Pass the accumulated text (not individual chunks) as targetText; the hook handles incremental reveal internally.
Set isStreaming to false when the stream completes to snap to the final text.
Use speed='instant' for non-animated contexts like search results or when reduced motion is preferred.
Use for static text that does not change; the hook adds unnecessary overhead for non-streaming content.

Markdown

Signature

Showcases and examples

Usage

Related entries