ASCIIFont

Render large ASCII art text using decorative fonts

Overview

ASCIIFontRenderable renders text in large ASCII art fonts. It supports multiple font styles, gradient colors, text selection, and transparent backgrounds. Perfect for headers, logos, and decorative text in terminal UIs.

Basic Usage

import { ASCIIFontRenderable, createCliRenderer } from '@opentui/core'

const renderer = await createCliRenderer()

const title = new ASCIIFontRenderable(renderer, {
  text: 'OpenTUI',
  font: 'block',
  color: '#00ff00',
})

renderer.root.add(title)

Available Fonts

// Tiny - compact font
const tiny = new ASCIIFontRenderable(renderer, {
  text: 'TINY FONT',
  font: 'tiny',
  color: '#ffff00',
})

// Block - bold block letters
const block = new ASCIIFontRenderable(renderer, {
  text: 'BLOCK',
  font: 'block',
  color: '#ff6b6b',
})

// Shade - shaded 3D effect
const shade = new ASCIIFontRenderable(renderer, {
  text: 'SHADE',
  font: 'shade',
  color: '#4ecdc4',
})

// Slick - clean modern style
const slick = new ASCIIFontRenderable(renderer, {
  text: 'SLICK',
  font: 'slick',
  color: '#95e1d3',
})

// Huge - very large letters
const huge = new ASCIIFontRenderable(renderer, {
  text: 'HUGE',
  font: 'huge',
  color: '#f38181',
})

// Grid - grid-based design
const grid = new ASCIIFontRenderable(renderer, {
  text: 'GRID',
  font: 'grid',
  color: '#aa96da',
})

// Pallet - palette-style font
const pallet = new ASCIIFontRenderable(renderer, {
  text: 'PALLET',
  font: 'pallet',
  color: '#fcbad3',
})

Gradient Colors

import { RGBA } from '@opentui/core'

// Two-color gradient
const gradient = new ASCIIFontRenderable(renderer, {
  text: 'GRADIENT',
  font: 'block',
  color: [
    RGBA.fromInts(255, 100, 100, 255),
    RGBA.fromInts(100, 100, 255, 255),
  ],
})

// Multi-color gradient
const rainbow = new ASCIIFontRenderable(renderer, {
  text: 'RAINBOW',
  font: 'shade',
  color: [
    '#ff0000',
    '#ff7f00',
    '#ffff00',
    '#00ff00',
    '#0000ff',
    '#4b0082',
    '#9400d3',
  ],
})

With Background

const boxed = new ASCIIFontRenderable(renderer, {
  text: 'BOXED',
  font: 'block',
  color: '#ffffff',
  backgroundColor: RGBA.fromInts(0, 0, 40, 255),
})

Text Selection

const selectable = new ASCIIFontRenderable(renderer, {
  text: 'SELECT ME',
  font: 'slick',
  color: '#00d4aa',
  selectable: true,
  selectionBg: '#4a5568',
  selectionFg: '#ffffff',
})

renderer.on('selection', (selection) => {
  const selectedText = selectable.getSelectedText()
  console.log('Selected:', selectedText)
})

Dynamic Text Updates

const dynamic = new ASCIIFontRenderable(renderer, {
  text: '0',
  font: 'huge',
  color: '#ff6b6b',
})

let counter = 0
setInterval(() => {
  counter++
  dynamic.text = counter.toString()
}, 1000)

React Usage

import { useState } from 'react'
import type { ASCIIFontName } from '@opentui/core'

export const Logo = () => {
  const [font, setFont] = useState<ASCIIFontName>('block')

  return (
    <box style={{ padding: 1 }}>
      <ascii-font
        text="OpenTUI"
        font={font}
        color="#00ff00"
      />
    </box>
  )
}

Props

text · string · default: "''"

The text to render in ASCII art. Automatically resizes the component when changed.

font · ASCIIFontName · default: "'tiny'"

The font style to use. Available fonts:

• 'tiny': Compact small font
• 'block': Bold block letters
• 'shade': Shaded 3D effect
• 'slick': Clean modern style
• 'huge': Very large letters
• 'grid': Grid-based design
• 'pallet': Palette-style font

color · ColorInput | ColorInput[] · default: "'#FFFFFF'"

Text color. Can be a single color or an array of colors for gradients.

// Single color
color: '#ff0000'

// Gradient
color: ['#ff0000', '#0000ff']

// RGBA object
color: RGBA.fromInts(255, 0, 0, 255)

backgroundColor · ColorInput · default: "'transparent'"

Background color behind the ASCII art.

selectable · boolean · default: "true"

Whether the text can be selected with mouse drag.

selectionBg · ColorInput

Background color for selected text.

selectionFg · ColorInput

Foreground color for selected text.

Properties

text

Get or set the displayed text.

asciiFont.text = 'NEW TEXT'
const current = asciiFont.text

font

Get or set the font style.

asciiFont.font = 'shade'
const currentFont = asciiFont.font

color

Get or set the text color(s).

asciiFont.color = '#00ff00'
asciiFont.color = ['#ff0000', '#0000ff']

backgroundColor

Get or set the background color.

asciiFont.backgroundColor = '#000000'

Methods

getSelectedText()

Get the currently selected text.

const selected = asciiFont.getSelectedText()
console.log('Selected:', selected)

hasSelection()

Check if there is an active selection.

if (asciiFont.hasSelection()) {
  console.log('Text is selected')
}

Common Patterns

Application Header

const header = new BoxRenderable(renderer, {
  width: '100%',
  border: true,
  borderStyle: 'double',
  padding: 1,
})

const logo = new ASCIIFontRenderable(renderer, {
  text: 'MyApp',
  font: 'block',
  color: ['#ff6b6b', '#4ecdc4'],
})

header.add(logo)

Loading Animation

const loadingStates = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
let frameIndex = 0

const loader = new ASCIIFontRenderable(renderer, {
  text: loadingStates[0],
  font: 'huge',
  color: '#00d4aa',
})

const interval = setInterval(() => {
  frameIndex = (frameIndex + 1) % loadingStates.length
  loader.text = loadingStates[frameIndex]
}, 100)

Status Display

function createStatusDisplay(status: 'OK' | 'ERROR' | 'WARN') {
  const colors = {
    OK: '#00ff00',
    ERROR: '#ff0000',
    WARN: '#ffff00',
  }

  return new ASCIIFontRenderable(renderer, {
    text: status,
    font: 'block',
    color: colors[status],
  })
}

Centered Title

const container = new BoxRenderable(renderer, {
  width: '100%',
  height: '100%',
  justifyContent: 'center',
  alignItems: 'center',
})

const title = new ASCIIFontRenderable(renderer, {
  text: 'Welcome',
  font: 'shade',
  color: ['#ff6b6b', '#f9ca24'],
})

container.add(title)

Interactive Font Selector

const fonts: ASCIIFontName[] = ['tiny', 'block', 'shade', 'slick', 'huge', 'grid', 'pallet']
let currentIndex = 0

const display = new ASCIIFontRenderable(renderer, {
  text: 'Sample',
  font: fonts[0],
  color: '#00d4aa',
})

renderer.keyInput.on('keypress', (key) => {
  if (key.name === 'space') {
    currentIndex = (currentIndex + 1) % fonts.length
    display.font = fonts[currentIndex]
  }
})

Font Characteristics

Size Comparison

• tiny: ~3 lines tall, compact
• block: ~5-6 lines tall, bold
• shade: ~5-6 lines tall, 3D shaded
• slick: ~5-6 lines tall, modern
• huge: ~8-10 lines tall, very large
• grid: ~6-7 lines tall, grid-based
• pallet: ~6-7 lines tall, palette design

Best Use Cases

• tiny: Space-constrained UIs, compact headers
• block: Bold statements, attention-grabbing titles
• shade: 3D effects, depth perception
• slick: Modern clean interfaces
• huge: Splash screens, prominent displays
• grid: Technical/retro aesthetics
• pallet: Artistic/decorative text

Performance Notes

• ASCII fonts automatically resize based on text content
• Font rendering is optimized with character position caching
• Gradient colors are applied efficiently per character
• Selection handling accounts for variable-width characters

Related Components

• Box - Container for ASCII fonts
• Text - Regular text rendering
• TextTable - Tabular data display