React component for rendering TAML (Terminal ANSI Markup Language) as styled JSX elements
npm install @taml/reactA React component for rendering TAML (Terminal ANSI Markup Language) as styled JSX elements.






TAML (Terminal ANSI Markup Language) is a lightweight markup language for styling terminal output with ANSI escape codes. For the complete specification, visit the TAML Specification Repository.
``mermaid`
graph TD
B["@taml/parser"] --> A["@taml/ast"]
C["@taml/react"] --> A
C --> B
D["@taml/docusaurus"] --> C
F["@taml/cli"] --> E["@taml/encoder"]
E -.-> A
E -.-> B
style C fill:#e1f5fe,stroke:#01579b,stroke-width:2px
#### Core Infrastructure
- @taml/ast - Foundation package providing AST node types, visitor patterns, and tree traversal utilities for TAML documents.
- @taml/parser - Robust parser that converts TAML markup strings into typed AST nodes with comprehensive error handling and validation.
#### Input/Output Tools
- @taml/encoder - Converts raw ANSI escape sequences into clean TAML markup for further processing and manipulation.
- @taml/cli - Command-line tool for converting ANSI escape sequences to TAML format in batch operations.
#### Integration Packages
- @taml/react - React component that renders TAML markup as styled JSX elements with full TypeScript support and performance optimization.
- @taml/docusaurus - Docusaurus theme that automatically detects and renders TAML code blocks in documentation sites.
- ๐จ Complete TAML Support: Renders all 37 TAML tags (colors, backgrounds, text styles)
- โก Performance Optimized: Built-in memoization and efficient rendering
- ๐ง TypeScript Ready: Full type safety with comprehensive TypeScript definitions
- ๐ฏ Zero Dependencies: Only requires React as a peer dependency
- ๐งช Well Tested: Comprehensive test suite with high coverage
- ๐ฆ Tree Shakable: Optimized for modern bundlers
- ๐ญ CSS Classes: Uses semantic CSS classes for easy customization
`bash`
npm install @taml/react
`bash`
yarn add @taml/react
`bash`
pnpm add @taml/react
`bash`
bun add @taml/react
This package includes TypeScript declarations out of the box. No additional setup is required for TypeScript projects.
`typescript
// ESM
import { Taml } from "@taml/react";
// CommonJS
const { Taml } = require("@taml/react");
`
`tsx
import { Taml } from '@taml/react';
import '@taml/react/styles.css';
function App() {
return (
Understanding TAML Strings vs JSX
Important: The
component expects TAML markup as a string, not JSX elements.$3
`tsx
{"Error: Something went wrong"}
{"Success! "}
`$3
`tsx
Error: Something went wrong
Success!
`The TAML tags like
, , etc. are markup syntax that gets parsed from the string, not React components.API Reference
$3
The main component for rendering TAML markup.
#### Props
| Prop | Type | Default | Description |
| ----------- | ------------------------ | ------------ | --------------------------------------------------- |
|
children | string | required | TAML markup string to parse and render |
| className | string | undefined | Additional CSS classes to apply to the root element |
| onError | (error: Error) => void | undefined | Callback function called when parsing fails |
| fallback | ReactNode | undefined | Fallback content to display when parsing fails |#### Example
`tsx
className="terminal-output"
onError={(error) => console.error('TAML Error:', error)}
fallback={Invalid TAML}
>
{"Error message "}
Supported TAML Tags
$3
- , , ,
- , , , $3
- , , ,
- , , , $3
- Standard: , , , etc.
- Bright: , , , etc.$3
- , , , , CSS Classes
Each TAML tag is rendered as a
element with corresponding CSS classes:- Root wrapper:
.taml
- Colors: .taml-red, .taml-green, .taml-blue, etc.
- Bright colors: .taml-bright-red, .taml-bright-green, etc.
- Backgrounds: .taml-bg-red, .taml-bg-green, etc.
- Bright backgrounds: .taml-bg-bright-red, .taml-bg-bright-green, etc.
- Text styles: .taml-bold, .taml-italic, .taml-underline, etc.Examples
$3
`tsx
import { Taml } from '@taml/react';
import '@taml/react/styles.css';// Simple colored text
{"Error: File not found"}
// Nested formatting
{"Critical: System failure"}
// Background colors
{" WARNING "}
`$3
`tsx
function LogViewer({ logs }) {
return (
{logs.map((entry, index) => (
{entry}
))}
);
}// Usage
const logs = [
"2024-12-07 10:30:15 [INFO] Application started",
"2024-12-07 10:30:16 [SUCCESS] Database connected",
"2024-12-07 10:30:45 [WARN] High memory usage",
"2024-12-07 10:31:02 [ERROR] Connection failed",
];
`$3
`tsx
function TerminalOutput() {
return (
{"user@computer :~/project $ npm test"}
{"Running tests... "}
{"โ All tests passed"}
);
}
`$3
`tsx
function SafeTamlRenderer({ content }) {
const handleError = (error) => {
console.error('Failed to parse TAML:', error.message);
}; return (
onError={handleError}
fallback={Invalid TAML content}
>
{content}
);
}
`Styling
$3
The package includes default CSS styles that map TAML tags to appropriate colors and formatting. Import the stylesheet:
`tsx
import '@taml/react/styles.css';
`$3
You can override the default styles or add your own:
`css
/ Override default colors /
.taml-red {
color: #ff4444;
}/ Add custom terminal styling /
.terminal .taml {
font-family: 'Courier New', monospace;
background: #1e1e1e;
color: #ffffff;
padding: 1rem;
border-radius: 4px;
}
/ Dark mode support /
@media (prefers-color-scheme: dark) {
.taml-white {
color: #ffffff;
}
.taml-black {
color: #808080;
}
}
`$3
For dynamic theming, you can use CSS custom properties:
`css
.taml {
--taml-red: #ff0000;
--taml-green: #00ff00;
--taml-blue: #0000ff;
}.taml-red {
color: var(--taml-red);
}
`Advanced Usage
$3
The package exports utility functions for advanced use cases:
`tsx
import {
generateClassName,
combineClassNames,
renderTamlNode
} from '@taml/react';
import { parseAml } from '@taml/parser';// Generate CSS class name from TAML tag
const className = generateClassName('brightRed'); // 'taml-bright-red'
// Combine multiple class names
const combined = combineClassNames('taml', 'custom', undefined); // 'taml custom'
// Parse TAML to AST (import from @taml/parser)
const ast = parseAml('Hello ');
// Render AST node to React element
const element = renderTamlNode(ast);
`$3
The component includes built-in performance optimizations:
- Memoization: Parsed results are cached for identical input strings
- Efficient rendering: Minimal React element creation
- Tree shaking: Only import what you need
`tsx
import { clearRenderCache, getCacheStats } from '@taml/react';// Clear the render cache if needed
clearRenderCache();
// Get cache statistics
const stats = getCacheStats();
console.log(
Cache size: ${stats.size}/${stats.maxSize});
`TypeScript Support
Full TypeScript support with comprehensive type definitions:
`tsx
import type { TamlProps, TamlTag } from '@taml/react';
import type { TamlNode } from '@taml/ast';// Component props are fully typed - children MUST be a string
const props: TamlProps = {
children: "Error ", // โ
String literal
className: 'custom',
onError: (error: Error) => console.error(error),
fallback: Fallback
};
// This would cause a TypeScript error:
// const invalidProps: TamlProps = {
// children: Error , // โ JSX element - TypeScript error
// };
// TAML tags are type-checked
const validTag: TamlTag = 'red'; // โ
const invalidTag: TamlTag = 'purple'; // โ TypeScript error
// AST node types are imported from @taml/ast
const node: TamlNode = { / ... / };
`Common Mistakes
$3
`tsx
// โ Wrong - This treats as a JSX component
Error // โ
Correct - This treats as TAML markup
{"Error "}
`$3
`tsx
// โ Wrong - This passes the literal string "Error "
"Error " // โ
Correct - This passes the string content to be parsed
{"Error "}
`$3
`tsx
// โ Wrong - Mixing TAML strings with JSX elements
{"Error: "} Additional info // โ
Correct - Keep TAML content as pure strings
{"Error: Additional info"}
// Or use separate elements:
{"Error: "}
Additional info
`Browser Support
- Modern browsers with ES2022 support
- React 16.8+ (hooks support required)
- TypeScript 5.0+ (for TypeScript users)
Contributing
We welcome contributions! Please see our Contributing Guide for details.
$3
`bash
Clone the repository
git clone https://github.com/suin/taml-react.git
cd taml-reactInstall dependencies
bun installRun tests
bun testBuild the project
bun run buildLint and format
bun run lint
bun run format
`$3
The project uses Bun for testing with comprehensive test coverage:
`bash
Run all tests
bun testRun tests in watch mode
bun test --watchRun specific test file
bun test Taml.test.tsx
``MIT License - see LICENSE file for details.
---
Part of the TAML ecosystem - Visit the TAML Specification for more information about the Terminal ANSI Markup Language.