On this page

These docs describe the main branch, including unreleased changes. Read the 0.8.0 docs.

ASCIIFont

ASCIIFont draws short text with bundled ASCII art fonts. Use Text for normal labels and prose.

Availability

FieldAvailability
Package@opentui/core
Core renderableASCIIFontRenderable
React<ascii-font> (automatic)
Solid<ascii_font> (automatic)
StatusBuilt in

Basic usage

Renderable API

OpenTUI preview

Run this example to open an interactive terminal.

Source code · typescript
import { ASCIIFontRenderable, RGBA, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

const title = new ASCIIFontRenderable(renderer, {
  id: "title",
  text: "OPENTUI",
  font: "tiny",
  color: RGBA.fromInts(255, 255, 255, 255),
})

renderer.root.add(title)

Available fonts

OpenTUI includes several ASCII art font styles:

// Small, compact font
{
  font: "tiny"
}

// Block style font
{
  font: "block"
}

// Shaded style font
{
  font: "shade"
}

// Slick style font
{
  font: "slick"
}

// Large font
{
  font: "huge"
}

// Grid style font
{
  font: "grid"
}

// Pallet style font
{
  font: "pallet"
}

The tiny font draws OPEN in two rows:

█▀█ █▀█ █▀▀ █▄ █
█▄█ █▀▀ ██▄ █ ▀█

The block font draws the same text in six rows:

 ██████╗  ██████╗  ███████╗ ███╗   ██╗
██╔═══██╗ ██╔══██╗ ██╔════╝ ████╗  ██║
██║   ██║ ██████╔╝ █████╗   ██╔██╗ ██║
██║   ██║ ██╔═══╝  ██╔══╝   ██║╚██╗██║
╚██████╔╝ ██║      ███████╗ ██║ ╚████║
 ╚═════╝  ╚═╝      ╚══════╝ ╚═╝  ╚═══╝

Positioning

ASCIIFont inherits the standard layout positioning options. To position it at coordinates relative to its parent, use absolute positioning with left and top:

const title = new ASCIIFontRenderable(renderer, {
  id: "title",
  text: "TITLE",
  font: "block",
  color: RGBA.fromHex("#FFFF00"),
  position: "absolute",
  left: 10,
  top: 2,
})

Properties

PropertyTypeDefaultDescription
textstring""Text to display
fontASCIIFontName"tiny"Font style
colorColorInput | ColorInput[]"#FFFFFF"Text color or color bands
backgroundColorColorInput"transparent"Background color
selectablebooleantrueWhether text is selectable
selectionBgColorInput-Selection background color
selectionFgColorInput-Selection foreground color
position"relative" | "absolute""relative"Effective positioning mode
topnumber, "auto", or percentage string-Top position offset
rightnumber, "auto", or percentage string-Right position offset
bottomnumber, "auto", or percentage string-Bottom position offset
leftnumber, "auto", or percentage string-Left position offset

Example: welcome screen

OpenTUI preview

Run this example to open an interactive terminal.

Source code · typescript
import { ASCIIFontRenderable, BoxRenderable, TextRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

const welcomeScreen = new BoxRenderable(renderer, {
  width: "100%",
  height: "100%",
  flexDirection: "column",
  alignItems: "center",
  justifyContent: "center",
})
welcomeScreen.add(
  new ASCIIFontRenderable(renderer, {
    text: "OPENTUI",
    font: "huge",
    color: "#00FFFF",
  }),
)
welcomeScreen.add(
  new TextRenderable(renderer, {
    content: "Terminal UI Framework",
    fg: "#888888",
  }),
)
welcomeScreen.add(
  new TextRenderable(renderer, {
    content: "Press any key to continue...",
    fg: "#444444",
  }),
)

renderer.root.add(welcomeScreen)

Dynamic text

Update the text content dynamically:

const counter = new ASCIIFontRenderable(renderer, {
  id: "counter",
  text: "0",
  font: "block",
  color: RGBA.fromHex("#FF0000"),
})

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

Color effects

Create a shadow by overlaying two ASCII fonts:

OpenTUI preview

Run this example to open an interactive terminal.

Source code · typescript
import { ASCIIFontRenderable, BoxRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()
const shadowTitle = new BoxRenderable(renderer, { position: "relative" })
shadowTitle.add(
  new ASCIIFontRenderable(renderer, {
    text: "HELLO",
    font: "block",
    color: "#880000",
    position: "absolute",
    left: 1,
    top: 1,
    zIndex: 0,
  }),
)
shadowTitle.add(
  new ASCIIFontRenderable(renderer, {
    text: "HELLO",
    font: "block",
    color: "#FF0000",
    zIndex: 1,
  }),
)
renderer.root.add(shadowTitle)

See Layout for positioning and Colors for accepted color values. Use FrameBuffer for graphics that need direct cell drawing.