BlazorFastTypewriter 1.0.4

Blazor Fast Typewriter

A high-performance typewriter component for Blazor that animates text character-by-character with full HTML support. Built with .NET 10 features for optimal performance, AOT compilation, and aggressive trimming.

Why another typewriter? Shipping to WebAssembly or native AOT targets demands components that are deterministic, trimming-safe, and optimized from the first render. This component was built from the ground up with those goals, using modern .NET 10 features for maximum performance.

Live Demo

🚀 View the interactive demo

Table of Contents

• Quick Start
• Features
• Basic Usage
• API Reference
  • Parameters
  • Methods
  • Properties
  • Events
• Advanced Usage
  • Seek & Scrubbing
  • Dynamic Content Updates
  • Accessibility
  • Production Builds
• Technical Details
• Testing
• License

Quick Start

1. Install the package

dotnet add package BlazorFastTypewriter

2. Add the namespace to _Imports.razor

@using BlazorFastTypewriter

3. Use the component

<Typewriter Speed="100">
    <p>Welcome to Blazor Fast Typewriter!</p>
</Typewriter>

That's it! CSS and JavaScript are automatically included via Blazor's static web assets.

Features

🎯 Core Features

• Full HTML Support — Preserves tags, links, code blocks, and nested structures
• High Performance — Optimized with modern .NET 10 features (ImmutableArray.Builder, collection expressions, pattern matching)
• Bidirectional Text — Supports LTR and RTL text direction
• Composable — Works with any child content: text, components, images, or complex layouts

⚙️ Build Features

• Trimming-Friendly — Library is marked as trimmable and ships without reflection
• AOT Ready — Validated against Native AOT constraints with RunAOTCompilation enabled
• Zero Configuration — CSS and JavaScript are automatically bundled via static web assets

🎮 Control Features

• Playback Control — Start, pause, resume, complete, and reset with event callbacks
• Seek & Scrubbing — Jump to any position in the animation with Seek(), SeekToPercent(), or SeekToChar()
• Progress Tracking — Real-time progress events every 10 characters
• Dynamic Content — Update content programmatically with SetText() methods

♿ Accessibility Features

• ARIA Live Regions — Automatic aria-live="polite" and aria-atomic="false" for screen readers
• Reduced Motion Support — Respects prefers-reduced-motion media query when enabled
• Semantic Markup — Proper ARIA labels and role attributes

Basic Usage

Simple Animation

<Typewriter Speed="100" Autostart="true">
    <p>A simple typewriter with <strong>HTML support</strong>.</p>
</Typewriter>

Manual Playback Control

<Typewriter @ref="_typewriter" Speed="60" Autostart="false">
    <p>Click the buttons to control the animation.</p>
</Typewriter>

<button @onclick="() => _typewriter?.Start()">Start</button>
<button @onclick="() => _typewriter?.Pause()">Pause</button>
<button @onclick="() => _typewriter?.Resume()">Resume</button>
<button @onclick="() => _typewriter?.Complete()">Complete</button>

@code {
    private Typewriter? _typewriter;
}

Progress Tracking

<Typewriter Speed="80" OnProgress="HandleProgress">
    <p>Content to animate...</p>
</Typewriter>

<p>Progress: @_progress%</p>

@code {
    private double _progress = 0;
    
    private void HandleProgress(TypewriterProgressEventArgs args)
    {
        _progress = args.Percent;
    }
}

RTL (Right-to-Left) Support

<Typewriter Dir="rtl" Speed="80">
    <p>يدعم المكوّن <strong>النصوص العربية</strong> مع الحفاظ على الاتجاه الصحيح.</p>
</Typewriter>

Rich HTML Content

<Typewriter Speed="60">
    <div>
        <h2>Rich Content</h2>
        <p>Supports <strong>bold</strong>, <em>italic</em>, and <a href="#">links</a>.</p>
        <ul>
            <li>Lists with <code>inline code</code></li>
            <li>Nested <strong>formatting</strong></li>
        </ul>
    </div>
</Typewriter>

API Reference

Parameters

Methods

Properties

Events

TypewriterProgressEventArgs

Provides progress information:

• Current (int) — Characters animated so far
• Total (int) — Total characters to animate
• Percent (double) — Percentage complete (0-100)

TypewriterSeekEventArgs

Provides seek information:

• Position (double) — Normalized position (0.0 to 1.0)
• TargetChar (int) — Character index seeked to
• TotalChars (int) — Total number of characters
• Percent (double) — Percentage complete (0-100)
• WasRunning (bool) — Whether animation was running before seek
• CanResume (bool) — Whether animation can be resumed
• AtStart (bool) — Whether seek landed at start
• AtEnd (bool) — Whether seek landed at end

TypewriterProgressInfo

Returned by GetProgress():

• Current (int) — Current character count
• Total (int) — Total character count
• Percent (double) — Percentage complete (0-100)
• Position (double) — Normalized position (0.0 to 1.0)

Advanced Usage

Seek & Scrubbing

Jump to any position in the animation with full scrubbing support:

<Typewriter @ref="_typewriter" Speed="60" OnProgress="UpdatePosition">
    <p>Content to animate with seek support...</p>
</Typewriter>

<label>
    Position: @_position%
    <input type="range" min="0" max="100" value="@_position" 
           @oninput="e => SeekToPosition(e)" />
</label>

<button @onclick="() => _typewriter?.Seek(0)">Start</button>
<button @onclick="() => _typewriter?.Seek(0.5)">50%</button>
<button @onclick="() => _typewriter?.Seek(1)">End</button>

@code {
    private Typewriter? _typewriter;
    private double _position = 0;
    
    private async Task SeekToPosition(ChangeEventArgs e)
    {
        if (double.TryParse(e.Value?.ToString(), out var value))
        {
            _position = value;
            await (_typewriter?.SeekToPercent(value) ?? Task.CompletedTask);
        }
    }
    
    private void UpdatePosition(TypewriterProgressEventArgs args)
    {
        _position = args.Percent;
    }
}

Dynamic Content Updates

Update content programmatically at runtime:

<Typewriter @ref="_typewriter" Autostart="false">
    @_content
</Typewriter>

<button @onclick="UpdateContent">Update Content</button>

@code {
    private Typewriter? _typewriter;
    private RenderFragment _content = builder => 
        builder.AddMarkupContent(0, "<p>Initial content</p>");
    
    private async Task UpdateContent()
    {
        await (_typewriter?.SetText("<p>New <strong>dynamic</strong> content!</p>") 
            ?? Task.CompletedTask);
        await (_typewriter?.Start() ?? Task.CompletedTask);
    }
}

Accessibility

Reduced Motion Support

Respects user preferences for reduced motion:

<Typewriter RespectMotionPreference="true" Speed="100">
    <p>This animation respects user motion preferences.</p>
</Typewriter>

ARIA Labels

Provide context for screen readers:

<Typewriter AriaLabel="Chat message being typed">
    <p>Message content...</p>
</Typewriter>

Best Practices

• Keep Speed between 50-150 chars/sec for comfortable reading
• Enable RespectMotionPreference for accessibility compliance
• Provide AriaLabel when typewriter conveys essential information
• Use semantic HTML inside ChildContent
• Consider offering pause controls for longer animations

Production Builds

The component is optimized for trimming and Native AOT compilation:

dotnet publish -c Release \
  -p:PublishTrimmed=true \
  -p:TrimMode=link \
  -p:RunAOTCompilation=true

Notes:

• The library opts into invariant globalization to minimize ICU payload size
• If your app requires full globalization, override InvariantGlobalization in your project file
• No reflection is used — fully trimming-safe
• Validated with trimming analyzers and Native AOT constraints

Technical Details

Architecture

DOM Extraction — Uses JavaScript interop to extract rendered DOM structure, preserving all HTML tags and attributes.

Operation Queue — Converts DOM structure into an immutable array of operations (open tag, character, close tag) for efficient processing.

Animation Loop — Runs on background thread using Task.Run with proper cancellation token support for responsive UI.

Thread Safety — All UI updates use InvokeAsync to ensure thread-safe rendering and prevent race conditions.

Modern .NET 10 Features

• Collection Expressions — [] for empty arrays, [..] for spread operations
• ImmutableArray.Builder — Efficient immutable array building without allocations
• Pattern Matching — Modern syntax like is null or { Length: 0 }
• Primary Constructors — Records use concise primary constructor syntax
• Lock — Uses new Lock type for thread-safe operations
• Random.Shared — Thread-safe randomization for character delays

Performance Optimizations

• Minimal Allocations — Pre-allocated StringBuilder with capacity and ImmutableArray.Builder
• Cancellation Tokens — Proper disposal to prevent memory leaks
• Efficient Parsing — Single-pass DOM structure parsing
• Smart Delays — Only delays for character operations, not tag operations
• Generation Counter — Efficient animation lifecycle management

Testing

The project includes comprehensive BUnit tests covering:

• Component rendering and lifecycle
• Playback control methods
• Event callbacks and parameter forwarding
• Edge cases and error handling

Run tests locally:

dotnet test

License

MIT