Text Effects

# Brok UI: Typewriter (`typewriter`)

Types and deletes through one or more words with a blinking caret, looping by default and respecting reduced-motion.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add typewriter
```

## Usage

```blade
<p class="text-3xl font-bold text-foreground">
    We build <x-ui.typewriter :words="['websites', 'apps', 'brands']" class="text-primary" />
</p>
```

## Props

- `words` (array, default `[]`) — Word or words to type and delete through, in order; a single string is also accepted.
- `loop` (bool, default `true`) — Restarts from the first word after the last one deletes; false stops after the last word types.
- `typeSpeed` (int, default `80`) — Milliseconds per typed character.
- `deleteSpeed` (int, default `40`) — Milliseconds per deleted character.
- `pauseMs` (int, default `1500`) — Milliseconds to pause on a fully typed word before deleting it.
- `cursor` (bool, default `true`) — Shows a blinking caret after the text.
- `reserve` (bool, default `true`) — Reserves the width of the longest word so surrounding content never shifts as words grow and shrink.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Typing and deleting through one or more words with a blinking caret, for a hero tagline or rotating headline.
- Wanting the text column width reserved so surrounding content does not shift as words grow and shrink.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Typing long paragraphs of body copy; the effect is best for short words or phrases.
- Needing a one-shot reveal instead of an endless type/delete loop; use text-animate or kinetic-text-reveal instead.

## Anti-patterns

- Heavy effects in forms or task-dense workflows
- Motion that interferes with reading or focus

## Rules

- Use the `<brok:typewriter>` tag (or `<x-ui.typewriter>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/typewriter
- Registry JSON (files, props, contract): https://brokui.dev/r/open/typewriter.json

@props([
    'words' => [],
    'loop' => true,
    'typeSpeed' => 80,
    'deleteSpeed' => 40,
    'pauseMs' => 1500,
    'cursor' => true,
    // Keep the width of the longest word, so the text after the typewriter
    // (and a centred line around it) never shifts as words grow and shrink.
    'reserve' => true,
])

@php
    // Normalize `words` to an array so a single string works too.
    $wordsArray = is_array($words) ? array_values($words) : [$words];
    $wordsArray = array_values(array_filter($wordsArray, fn ($w) => $w !== null && $w !== ''));
    if (empty($wordsArray)) {
        $wordsArray = [''];
    }
    // SSR fallback shows the first word so the text is correct before hydration.
    $firstWord = $wordsArray[0];
    $longest = array_reduce($wordsArray, fn ($carry, $w) => mb_strlen($w) > mb_strlen($carry) ? $w : $carry, '');
    $reserve = filter_var($reserve, FILTER_VALIDATE_BOOLEAN);

    $config = [
        'words' => $wordsArray,
        'loop' => (bool) $loop,
        'typeSpeed' => (int) $typeSpeed,
        'deleteSpeed' => (int) $deleteSpeed,
        'pauseMs' => (int) $pauseMs,
    ];
@endphp

<span
    data-slot="typewriter"
    x-data="uiTypewriter(@js($config))"
    role="img"
    aria-label="{{ implode(', ', $wordsArray) }}"
    {{ $attributes->merge(['class' => 'inline-grid items-baseline text-foreground '.($reserve ? 'text-start' : '')]) }}
>
    {{-- The longest word, invisible, holds the column width; the live text sits
         on top of it. A zero-width space keeps the line box while the word is
         empty, so the height never collapses between words. --}}
    @if ($reserve)
        <span aria-hidden="true" class="invisible col-start-1 row-start-1 inline-flex items-baseline whitespace-nowrap">
            <span>{{ $longest }}</span>
            @if ($cursor)<span class="ms-0.5 inline-block w-px"></span>@endif
        </span>
    @endif
    <span aria-hidden="true" class="col-start-1 row-start-1 inline-flex items-baseline whitespace-nowrap">
        <span x-text="display || '\u200b'">{{ $firstWord }}</span>
        @if ($cursor)
            <span
                class="ms-0.5 inline-block h-[1em] w-px translate-y-[0.1em] self-baseline bg-current motion-safe:animate-[ui-caret-blink_1s_steps(2)_infinite]"
            ></span>
        @endif
    </span>
</span>

/**
 * Typewriter behavior.
 *
 * Types through a list of words one character at a time, pauses at the full
 * word, then deletes and advances to the next. The full set of words is exposed
 * to assistive tech via `aria-label` on the root, so the animated `display`
 * span is `aria-hidden`. Honors reduced-motion by rendering the first word
 * statically. Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiTypewriter', (config = {}) => ({
        words: config.words ?? [],
        loop: config.loop ?? true,
        typeSpeed: config.typeSpeed ?? 80,
        deleteSpeed: config.deleteSpeed ?? 40,
        pauseMs: config.pauseMs ?? 1500,

        display: '',
        _wordIndex: 0,
        _charIndex: 0,
        _deleting: false,
        _timer: null,

        init() {
            if (!this.words.length) {
                return;
            }

            // Reduced motion: render the first word and skip all animation.
            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
                this.display = this.words[0];
                return;
            }

            this.display = '';
            this._charIndex = 0;
            this.tick();
        },

        tick() {
            const word = this.words[this._wordIndex] ?? '';

            if (!this._deleting) {
                // Typing forward.
                this._charIndex++;
                this.display = word.slice(0, this._charIndex);

                if (this._charIndex >= word.length) {
                    // Reached full word. If this is the last word and we are not
                    // looping, stop here.
                    const isLast = this._wordIndex === this.words.length - 1;
                    if (isLast && !this.loop) {
                        return;
                    }
                    this._deleting = true;
                    this._timer = setTimeout(() => this.tick(), this.pauseMs);
                    return;
                }

                this._timer = setTimeout(() => this.tick(), this.typeSpeed);
                return;
            }

            // Deleting.
            this._charIndex--;
            this.display = word.slice(0, Math.max(0, this._charIndex));

            if (this._charIndex <= 0) {
                this._deleting = false;
                this._charIndex = 0;
                this._wordIndex = (this._wordIndex + 1) % this.words.length;
                this._timer = setTimeout(() => this.tick(), this.typeSpeed);
                return;
            }

            this._timer = setTimeout(() => this.tick(), this.deleteSpeed);
        },

        destroy() {
            if (this._timer) {
                clearTimeout(this._timer);
                this._timer = null;
            }
        },
    }));
});