Termwind (nunomaduro/termwind)

Termwind

https://github.com/nunomaduro/termwind
Admin
Termwind allows you to build unique and beautiful PHP command-line applications using the Tailwind...

Tokens:9,864
Snippets:56
Trust Score:10
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Termwind

Termwind is a PHP library that brings the Tailwind CSS API to command-line applications. It allows developers to build beautiful terminal interfaces using familiar CSS utility classes like `bg-green-300`, `px-1`, `text-center`, and more. Instead of manually formatting terminal output with ANSI escape codes, developers can write HTML-like markup with Tailwind-style classes that render as styled console output.

The library is built on top of Symfony Console and provides a complete set of HTML elements (div, span, paragraph, tables, lists, etc.) that can be styled with Tailwind utility classes. It supports responsive design with breakpoints, custom color definitions, text formatting, spacing utilities, and interactive features like prompts. Termwind seamlessly integrates with Laravel and Symfony console commands, making it easy to create visually appealing CLI tools with minimal effort.

## Core Functions

### render() - Display HTML in the terminal

The `render()` function takes HTML markup with Tailwind CSS classes and outputs styled content to the terminal. It's the primary way to display formatted text in CLI applications.

```php
<?php

use function Termwind\render;

// Basic styled output
render('<div class="px-1 bg-green-300">Termwind</div>');

// Multi-line HTML with nested elements
render(<<<'HTML'
    <div>
        <div class="px-1 bg-green-600 text-white">Welcome to Termwind</div>
        <em class="ml-1">Give your CLI apps a unique look</em>
    </div>
HTML);

// Using various Tailwind classes
render(<<<'HTML'
    <div class="mt-2">
        <p class="text-center font-bold underline">Status Report</p>
        <div class="bg-blue-500 text-white p-2 mt-1">Processing: 75%</div>
        <span class="text-green ml-2">✓ Complete</span>
    </div>
HTML);

// Responsive design with breakpoints
render(<<<'HTML'
    <div class="bg-blue-500 sm:bg-red-600 lg:bg-green-500">
        Background changes color based on terminal width
    </div>
HTML);
```

### style() - Create custom styles and colors

The `style()` function allows you to define custom CSS classes or override existing color definitions. It enables extending Termwind's styling capabilities beyond the default Tailwind classes.

```php
<?php

use function Termwind\{style, render};

// Define a custom color
style('green-300')->color('#bada55');

// Create a custom button style
style('btn')->apply('p-4 bg-green-300 text-white font-bold');

// Create a custom alert style
style('alert')->apply('px-2 py-1 bg-red-500 text-white');

// Use custom styles
render('<div class="btn">Click me</div>');
render('<div class="alert">Warning: Operation failed!</div>');

// Create a style with custom behavior
style('highlight')->color('#ffff00')->apply('font-bold underline');
render('<span class="highlight">Important text</span>');
```

### ask() - Prompt user for input

The `ask()` function displays a styled prompt and waits for user input, returning the user's response. It supports HTML markup with Tailwind classes for styled prompts and optional autocomplete functionality.

```php
<?php

use function Termwind\{ask, render};

// Simple question
$name = ask('<span class="mt-1 ml-2 mr-1 bg-green px-1 text-black">What is your name?</span>');
render("<p class='ml-2'>Hello, {$name}!</p>");

// Question with styling
$email = ask(<<<'HTML'
    <span class="bg-blue-500 text-white px-2 py-1">
        📧 Enter your email address:
    </span>
HTML);

// Question with autocomplete options
$framework = ask(
    '<span class="bg-purple px-1">Choose a framework:</span>',
    ['Laravel', 'Symfony', 'CodeIgniter', 'Yii']
);

// Building an interactive form
$username = ask('<span class="bg-cyan px-1 text-black">Username:</span>');
$password = ask('<span class="bg-cyan px-1 text-black">Password:</span>');

render(<<<HTML
    <div class="mt-1 ml-2">
        <p class="text-green">✓ Account created for: {$username}</p>
    </div>
HTML);
```

### terminal() - Access terminal properties

The `terminal()` function returns a Terminal object that provides methods to interact with the terminal environment, including getting dimensions and clearing the screen.

```php
<?php

use function Termwind\{terminal, render};

$term = terminal();

// Get terminal dimensions
$width = $term->width();
$height = $term->height();

render(<<<HTML
    <div class="ml-2 mt-1">
        <p>Terminal dimensions: {$width}x{$height}</p>
    </div>
HTML);

// Clear the terminal screen
$term->clear();

// Create responsive layouts based on width
if ($width > 100) {
    render('<div class="flex justify-between"><span>Left</span><span>Right</span></div>');
} else {
    render('<div><div>Left</div><div>Right</div></div>');
}

// Center content based on terminal width
$contentWidth = 50;
$padding = (int) (($width - $contentWidth) / 2);
render(<<<HTML
    <div class="ml-{$padding}">
        <div class="w-{$contentWidth} bg-blue-500 text-white text-center p-2">
            Centered Content
        </div>
    </div>
HTML);
```

### parse() - Convert HTML to terminal string

The `parse()` function converts HTML markup with Tailwind classes into a formatted string that can be rendered in the terminal, without immediately displaying it. Useful for preparing output that will be used later.

```php
<?php

use function Termwind\{parse, render};

// Parse HTML to string
$output = parse('<div class="bg-green-300 px-1">Status: OK</div>');

// Store parsed outputs
$header = parse('<p class="font-bold text-center">Application Report</p>');
$footer = parse('<p class="text-gray mt-2">Generated at ' . date('Y-m-d H:i:s') . '</p>');

// Combine and render later
$fullReport = $header . "\n" . $output . "\n" . $footer;
echo $fullReport;

// Prepare dynamic content
$messages = [];
foreach (['info', 'warning', 'error'] as $type) {
    $messages[$type] = parse("<span class='bg-{$type} px-1'>{$type} message</span>");
}

// Conditionally display based on logic
$severity = 'error';
echo $messages[$severity];
```

### renderUsing() - Set custom output handler

The `renderUsing()` function allows you to specify a custom OutputInterface implementation for rendering, enabling integration with Symfony Console OutputInterface or custom output handlers.

```php
<?php

use Symfony\Component\Console\Output\ConsoleOutput;
use Symfony\Component\Console\Output\BufferedOutput;
use function Termwind\{renderUsing, render};

// Use standard console output (default)
renderUsing(new ConsoleOutput());
render('<div class="text-green">Standard output</div>');

// Use buffered output for testing
$buffer = new BufferedOutput();
renderUsing($buffer);
render('<div class="bg-blue-500">Buffered content</div>');
$content = $buffer->fetch();
assert(str_contains($content, 'Buffered content'));

// Reset to default
renderUsing(null);

// Use in Symfony Console Command
class MyCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        renderUsing($output);
        render('<div class="text-green">✓ Command executed</div>');
        return Command::SUCCESS;
    }
}
```

## HTML Elements

### Lists - Unordered and ordered lists

Create bullet and numbered lists using `<ul>`, `<ol>`, and `<li>` tags with full styling support. Lists support Tailwind classes and can be customized with different list styles.

```php
<?php

use function Termwind\render;

// Unordered list with default disc bullets
render(<<<'HTML'
    <ul>
        <li>First item</li>
        <li>Second item</li>
        <li>Third item</li>
    </ul>
HTML);

// Ordered list with numbers
render(<<<'HTML'
    <ol class="ml-2">
        <li>Initialize project</li>
        <li>Install dependencies</li>
        <li>Run tests</li>
    </ol>
HTML);

// Custom styled lists
render(<<<'HTML'
    <div class="mt-2">
        <p class="font-bold">Features:</p>
        <ul class="list-square ml-4 text-green">
            <li>Fast rendering</li>
            <li>Tailwind CSS API</li>
            <li>Responsive design</li>
        </ul>
    </div>
HTML);

// Nested lists
render(<<<'HTML'
    <ol class="ml-2">
        <li>Backend Tasks
            <ul class="list-disc ml-4">
                <li>Setup database</li>
                <li>Create migrations</li>
            </ul>
        </li>
        <li>Frontend Tasks</li>
    </ol>
HTML);
```

### Description Lists - Definition lists

Description lists use `<dl>`, `<dt>`, and `<dd>` tags to create term-definition pairs, ideal for displaying configuration options, glossaries, or key-value information.

```php
<?php

use function Termwind\render;

// Basic description list
render(<<<'HTML'
    <dl>
        <dt>Termwind</dt>
        <dd>A PHP library for terminal styling</dd>
        <dt>Composer</dt>
        <dd>Dependency manager for PHP</dd>
    </dl>
HTML);

// Styled configuration display
render(<<<'HTML'
    <div class="mt-1 ml-2">
        <p class="font-bold text-blue">Application Configuration</p>
        <dl class="mt-1">
            <dt class="text-green">Environment</dt>
            <dd class="ml-4 text-gray">production</dd>
            <dt class="text-green">Debug Mode</dt>
            <dd class="ml-4 text-gray">disabled</dd>
            <dt class="text-green">Cache Driver</dt>
            <dd class="ml-4 text-gray">redis</dd>
        </dl>
    </div>
HTML);

// Feature showcase
render(<<<'HTML'
    <dl class="ml-2">
        <dt>🎨 Styling</dt>
        <dd>Tailwind CSS utility classes</dd>
        <dt>📱 Responsive</dt>
        <dd>Breakpoint-based layouts</dd>
        <dt>⚡ Fast</dt>
        <dd>Optimized rendering engine</dd>
    </dl>
HTML);
```

### Tables - Structured data display

Tables support `<table>`, `<thead>`, `<tr>`, `<th>`, and `<td>` tags for displaying tabular data with automatic formatting and optional styling.

```php
<?php

use function Termwind\render;

// Basic table
render(<<<'HTML'
    <table>
        <thead>
            <tr>
                <th>Name</th>
                <th>Status</th>
            </tr>
        </thead>
        <tr>
            <td>Termwind</td>
            <td>✓ Active</td>
        </tr>
        <tr>
            <td>Parser</td>
            <td>✓ Active</td>
        </tr>
    </table>
HTML);

// Styled table with classes
render(<<<'HTML'
    <div class="mt-2">
        <table class="ml-2">
            <thead>
                <tr>
                    <th class="text-blue">Task</th>
                    <th class="text-blue">Progress</th>
                    <th class="text-blue">Status</th>
                </tr>
            </thead>
            <tr>
                <td>Build</td>
                <td>100%</td>
                <td class="text-green">✓ Done</td>
            </tr>
            <tr>
                <td>Test</td>
                <td>75%</td>
                <td class="text-yellow">⧗ Running</td>
            </tr>
            <tr>
                <td>Deploy</td>
                <td>0%</td>
                <td class="text-gray">○ Pending</td>
            </tr>
        </table>
    </div>
HTML);
```

### Text Formatting - Bold, italic, underline, strikethrough

Use semantic HTML tags like `<b>`, `<strong>`, `<i>`, `<em>`, `<u>`, and `<s>` for text formatting, or apply Tailwind classes for custom styling.

```php
<?php

use function Termwind\render;

// Basic formatting tags
render(<<<'HTML'
    <div class="ml-2 mt-1">
        <p>This is <b>bold text</b> and this is <i>italic text</i></p>
        <p>This is <u>underlined</u> and this is <s>strikethrough</s></p>
        <p>Use <strong>strong</strong> for important text and <em>emphasis</em> for emphasis</p>
    </div>
HTML);

// Combining formatting with colors
render(<<<'HTML'
    <div class="ml-2">
        <p class="text-green"><b>✓ Success:</b> Operation completed</p>
        <p class="text-red"><b>✗ Error:</b> <s>Invalid input</s></p>
        <p class="text-blue"><i>Note: Configuration updated</i></p>
    </div>
HTML);

// Tailwind class formatting
render(<<<'HTML'
    <div class="ml-2">
        <span class="font-bold text-white bg-blue-500 px-1">BOLD & STYLED</span>
        <span class="italic underline ml-2">Italic with underline</span>
        <span class="line-through text-gray ml-2">Deprecated feature</span>
    </div>
HTML);
```

### Links - Clickable hyperlinks

The `<a>` tag with `href` attribute creates clickable links in terminals that support them, allowing users to open URLs by clicking.

```php
<?php

use function Termwind\render;

// Basic link
render('<p>Visit <a href="https://github.com/nunomaduro/termwind">Termwind on GitHub</a></p>');

// Styled links
render(<<<'HTML'
    <div class="ml-2 mt-1">
        <p>Documentation: <a href="https://termwind.com" class="text-blue underline">termwind.com</a></p>
        <p>Issues: <a href="https://github.com/nunomaduro/termwind/issues" class="text-red">Report a bug</a></p>
    </div>
HTML);

// Links in lists
render(<<<'HTML'
    <div class="ml-2">
        <p class="font-bold">Resources:</p>
        <ul class="list-disc ml-4">
            <li><a href="https://tailwindcss.com">Tailwind CSS Docs</a></li>
            <li><a href="https://symfony.com/console">Symfony Console</a></li>
            <li><a href="https://laravel.com">Laravel Framework</a></li>
        </ul>
    </div>
HTML);
```

### Code Blocks - Syntax highlighting

The `<code>` tag displays code with syntax highlighting and line numbers. Use `line` and `start-line` attributes to highlight specific lines.

```php
<?php

use function Termwind\render;

// Code block with line numbers
render(<<<'HTML'
    <code>
        function hello() {
            echo "Hello, World!";
        }
    </code>
HTML);

// Highlight specific line
render(<<<'HTML'
    <code line="22" start-line="20">
        try {
            throw new \Exception('Something went wrong');
        } catch (\Throwable $e) {
            report($e);
        }
    </code>
HTML);

// Preformatted text with <pre>
render(<<<'HTML'
    <pre class="ml-2 bg-gray-800 text-white p-2">
        Text in a pre element
        it preserves
        both      spaces and
        line breaks
    </pre>
HTML);
```

## Tailwind CSS Classes

### Spacing - Margin and padding utilities

Termwind supports all Tailwind spacing utilities including margin (`m-*`), padding (`p-*`), and their directional variants (`ml-*`, `px-*`, `my-*`, etc.).

```php
<?php

use function Termwind\render;

// Margin utilities
render(<<<'HTML'
    <div class="mt-2">Top margin</div>
    <div class="mb-1">Bottom margin</div>
    <div class="ml-4">Left margin (indent)</div>
    <div class="mx-2">Horizontal margins</div>
    <div class="my-1">Vertical margins</div>
HTML);

// Padding utilities
render(<<<'HTML'
    <div class="p-2 bg-blue-500">Padding all sides</div>
    <div class="px-3 bg-green-500">Horizontal padding</div>
    <div class="py-1 bg-red-500">Vertical padding</div>
    <div class="pt-2 pb-1 pl-4 pr-2 bg-yellow-500">Individual padding</div>
HTML);

// Combining spacing with other styles
render(<<<'HTML'
    <div class="ml-2 mt-1 p-2 bg-gray-800 text-white">
        <p class="mb-1 font-bold">Title</p>
        <p class="ml-2">Indented content with spacing</p>
    </div>
HTML);
```

### Colors - Background and text colors

Apply background colors with `bg-{color}-{variant}` and text colors with `text-{color}-{variant}`. Supports all standard Tailwind color palettes.

```php
<?php

use function Termwind\render;

// Background colors
render(<<<'HTML'
    <div>
        <div class="bg-red-500 text-white px-2">Red background</div>
        <div class="bg-green-500 text-white px-2">Green background</div>
        <div class="bg-blue-500 text-white px-2">Blue background</div>
        <div class="bg-yellow-300 text-black px-2">Yellow background</div>
    </div>
HTML);

// Text colors
render(<<<'HTML'
    <div class="ml-2">
        <p class="text-red">Error message</p>
        <p class="text-green">Success message</p>
        <p class="text-blue">Information</p>
        <p class="text-gray">Muted text</p>
    </div>
HTML);

// Color variants
render(<<<'HTML'
    <div>
        <span class="bg-blue-300 px-1">Light blue</span>
        <span class="bg-blue-500 px-1 ml-1">Medium blue</span>
        <span class="bg-blue-700 text-white px-1 ml-1">Dark blue</span>
    </div>
HTML);
```

### Typography - Font styles and text transforms

Control text appearance with font weight, style, decoration, transformation, and alignment utilities.

```php
<?php

use function Termwind\render;

// Font weight and style
render(<<<'HTML'
    <div class="ml-2">
        <p class="font-bold">Bold text</p>
        <p class="font-normal">Normal text</p>
        <p class="italic">Italic text</p>
    </div>
HTML);

// Text decoration
render(<<<'HTML'
    <div class="ml-2">
        <p class="underline">Underlined text</p>
        <p class="line-through">Strikethrough text</p>
    </div>
HTML);

// Text transformation
render(<<<'HTML'
    <div class="ml-2">
        <p class="uppercase">uppercase text</p>
        <p class="lowercase">LOWERCASE TEXT</p>
        <p class="capitalize">capitalize each word</p>
    </div>
HTML);

// Text alignment
render(<<<'HTML'
    <div class="w-50">
        <p class="text-left">Left aligned</p>
        <p class="text-center">Center aligned</p>
        <p class="text-right">Right aligned</p>
    </div>
HTML);

// Text overflow
render('<p class="w-10 truncate">This is a very long text that will be truncated</p>');
```

### Layout - Width, display, and flex utilities

Control element dimensions, visibility, and flexbox layouts with Tailwind's layout utilities.

```php
<?php

use function Termwind\render;

// Width utilities
render(<<<'HTML'
    <div>
        <div class="w-20 bg-blue-500">Width 20</div>
        <div class="w-full bg-green-500">Full width</div>
        <div class="w-auto bg-red-500">Auto width</div>
        <div class="min-w-10 bg-yellow-500">Minimum width</div>
        <div class="max-w-30 bg-purple-500">Maximum width content here</div>
    </div>
HTML);

// Display utilities
render(<<<'HTML'
    <div>
        <div class="block bg-blue-500">Block element</div>
        <span class="inline bg-green-500">Inline</span>
        <span class="inline bg-red-500">Inline</span>
        <div class="hidden">This is hidden</div>
        <div class="invisible">This is invisible but takes space</div>
    </div>
HTML);

// Flexbox utilities
render(<<<'HTML'
    <div class="flex justify-between w-50">
        <span>Left</span>
        <span>Right</span>
    </div>
    <div class="flex justify-center w-50">
        <span>Centered</span>
    </div>
    <div class="flex justify-around w-50">
        <span>A</span>
        <span>B</span>
        <span>C</span>
    </div>
    <div class="flex justify-evenly w-50">
        <span>Even</span>
        <span>Distribution</span>
    </div>
HTML);
```

## Summary

Termwind is primarily used for building visually appealing command-line interfaces in PHP applications. It excels in creating interactive CLI tools, progress indicators, status dashboards, and formatted output for console commands. The library is particularly valuable in Laravel Artisan commands, Symfony Console applications, build tools, deployment scripts, and developer utilities where presenting information clearly in the terminal enhances user experience. Its Tailwind CSS-based approach makes it intuitive for web developers to apply familiar styling patterns to CLI applications.

Integration with existing PHP applications is straightforward through Composer installation and namespace imports. The library works seamlessly with Laravel's service provider auto-discovery, integrates naturally with Symfony Console commands via the `renderUsing()` function, and can be used standalone in any PHP 8.2+ CLI script. Common patterns include wrapping Termwind rendering in reusable command classes, creating custom style libraries for consistent branding across CLI tools, and combining `ask()` with `render()` for interactive wizards and configuration tools. The library's flexibility allows it to be adopted incrementally, replacing existing echo statements with styled output without requiring architectural changes.