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

ASCIIFont

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

Availability#

Field	Availability
Package	`@opentui/core`
Core renderable	`ASCIIFontRenderable`
React	`<ascii-font>` (automatic)
Solid	`<ascii_font>` (automatic)
Status	Built in

Basic usage#

Renderable API#

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#

Property	Type	Default	Description
`text`	`string`	`""`	Text to display
`font`	`ASCIIFontName`	`"tiny"`	Font style
`color`	`ColorInput \| ColorInput[]`	`"#FFFFFF"`	Text color or color bands
`backgroundColor`	`ColorInput`	`"transparent"`	Background color
`selectable`	`boolean`	`true`	Whether text is selectable
`selectionBg`	`ColorInput`	-	Selection background color
`selectionFg`	`ColorInput`	-	Selection foreground color
`position`	`"relative" \| "absolute"`	`"relative"`	Effective positioning mode
`top`	number, `"auto"`, or percentage string	-	Top position offset
`right`	number, `"auto"`, or percentage string	-	Right position offset
`bottom`	number, `"auto"`, or percentage string	-	Bottom position offset
`left`	number, `"auto"`, or percentage string	-	Left position offset

Example: welcome screen#

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:

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.