https://github.com/patricklx/ember-tui
ember terminal ui library for interactive console applications
https://github.com/patricklx/ember-tui
Last synced: about 2 months ago
JSON representation
ember terminal ui library for interactive console applications
- Host: GitHub
- URL: https://github.com/patricklx/ember-tui
- Owner: patricklx
- Created: 2025-11-20T07:03:05.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T09:27:54.000Z (about 2 months ago)
- Last Synced: 2026-04-18T09:28:05.405Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 2.27 MB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-ember - ember-tui - Terminal UI library — build and test CLI tools using Ember.js with Flexbox layouts powered by Yoga (Libraries / Alternative Rendering)
README
# Ember TUI
> Ember.js Terminal UI Library. Build and test your CLI tool using ember.js.
Ember TUI provides the same component-based UI building experience that Ember.js offers in the browser, but for command-line apps.
It uses [Yoga](https://github.com/facebook/yoga) to build Flexbox layouts in the terminal, so most CSS-like properties are available in Ember TUI as well.
If you are already familiar with Ember.js, you already know Ember TUI.
Since Ember TUI is built on Ember.js, all features of Ember.js are supported.
Head over to the [Ember.js](https://emberjs.com) website for documentation on how to use it.
Only Ember TUI's methods are documented in this readme.
## start developing
to create a new terminal app just run
```
npx ember-tui create-app --pnpm
pnpm prebuild
pnpm start
```
that will create the app with emberjs blueprint and adjust some files for ember-tui
## Contents
- [Getting Started](#getting-started)
- [Components](#components)
- [``](#text)
- [``](#box)
- [``](#newline)
- [``](#spacer)
- [``](#static)
- [``](#transform)
- [API](#api)
- [Examples](#examples)
## Getting Started
Ember TUI uses [Yoga](https://github.com/facebook/yoga), a Flexbox layout engine, to build great user interfaces for your CLIs using familiar CSS-like properties you've used when building apps for the browser.
It's important to remember that each element is a Flexbox container.
Think of it as if every `
` in the browser had `display: flex`.
See [``](#box) built-in component below for documentation on how to use Flexbox layouts in Ember TUI.
Note that all text must be wrapped in a [``](#text) component.
## Components
### ``
This component can display text and change its style to make it bold, underlined, italic, or strikethrough.
```glimmer-ts
import { render, Text } from 'ember-tui';
const template =
I am green
I am black on white
I am white
I am bold
I am italic
I am underline
I am strikethrough
I am inversed
;
render(template);
```
**Note:** `` allows only text nodes and nested `` components inside of it. For example, `` component can't be used inside ``.
#### color
Type: `string`
Change text color.
Ember TUI uses [chalk](https://github.com/chalk/chalk) under the hood, so all its functionality is supported.
```glimmer-ts
Green
Blue
Red
```
#### backgroundColor
Type: `string`
Same as `color` above, but for background.
```glimmer-ts
Green
Blue
Red
```
#### dimColor
Type: `boolean`\
Default: `false`
Dim the color (make it less bright).
```glimmer-ts
Dimmed Red
```
#### bold
Type: `boolean`\
Default: `false`
Make the text bold.
#### italic
Type: `boolean`\
Default: `false`
Make the text italic.
#### underline
Type: `boolean`\
Default: `false`
Make the text underlined.
#### strikethrough
Type: `boolean`\
Default: `false`
Make the text crossed with a line.
#### inverse
Type: `boolean`\
Default: `false`
Invert background and foreground colors.
```glimmer-ts
Inversed Yellow
```
#### wrap
Type: `string`\
Allowed values: `wrap` `truncate` `truncate-start` `truncate-middle` `truncate-end`\
Default: `wrap`
This property tells Ember TUI to wrap or truncate text if its width is larger than the container.
If `wrap` is passed (the default), Ember TUI will wrap text and split it into multiple lines.
If `truncate-*` is passed, Ember TUI will truncate text instead, resulting in one line of text with the rest cut off.
```glimmer-ts
Hello World
//=> 'Hello\nWorld'
// `truncate` is an alias to `truncate-end`
Hello World
//=> 'Hello…'
Hello World
//=> 'He…ld'
Hello World
//=> '…World'
```
### ``
`` is an essential Ember TUI component to build your layout.
It's like `
` in the browser.
```glimmer-ts
import { render, Box, Text } from 'ember-tui';
const template =
This is a box with margin
;
render(template);
```
#### Dimensions
##### width
Type: `number` `string`
Width of the element in spaces.
You can also set it as a percentage, which will calculate the width based on the width of the parent element.
```glimmer-ts
X
//=> 'X '
```
```glimmer-ts
X
Y
//=> 'X Y'
```
##### height
Type: `number` `string`
Height of the element in lines (rows).
You can also set it as a percentage, which will calculate the height based on the height of the parent element.
```glimmer-ts
X
//=> 'X\n\n\n'
```
##### minWidth
Type: `number`
Sets a minimum width of the element.
##### minHeight
Type: `number`
Sets a minimum height of the element.
#### Padding
##### paddingTop
Type: `number`\
Default: `0`
Top padding.
##### paddingBottom
Type: `number`\
Default: `0`
Bottom padding.
##### paddingLeft
Type: `number`\
Default: `0`
Left padding.
##### paddingRight
Type: `number`\
Default: `0`
Right padding.
##### paddingX
Type: `number`\
Default: `0`
Horizontal padding. Equivalent to setting `paddingLeft` and `paddingRight`.
##### paddingY
Type: `number`\
Default: `0`
Vertical padding. Equivalent to setting `paddingTop` and `paddingBottom`.
##### padding
Type: `number`\
Default: `0`
Padding on all sides. Equivalent to setting `paddingTop`, `paddingBottom`, `paddingLeft` and `paddingRight`.
```glimmer-ts
Top
Bottom
Left
Right
Left and right
Top and bottom
Top, bottom, left and right
```
#### Margin
##### marginTop
Type: `number`\
Default: `0`
Top margin.
##### marginBottom
Type: `number`\
Default: `0`
Bottom margin.
##### marginLeft
Type: `number`\
Default: `0`
Left margin.
##### marginRight
Type: `number`\
Default: `0`
Right margin.
##### marginX
Type: `number`\
Default: `0`
Horizontal margin. Equivalent to setting `marginLeft` and `marginRight`.
##### marginY
Type: `number`\
Default: `0`
Vertical margin. Equivalent to setting `marginTop` and `marginBottom`.
##### margin
Type: `number`\
Default: `0`
Margin on all sides. Equivalent to setting `marginTop`, `marginBottom`, `marginLeft` and `marginRight`.
```glimmer-ts
Top
Bottom
Left
Right
Left and right
Top and bottom
Top, bottom, left and right
```
#### Gap
##### gap
Type: `number`\
Default: `0`
Size of the gap between an element's columns and rows. A shorthand for `columnGap` and `rowGap`.
```glimmer-ts
A
B
C
// A B
//
// C
```
##### columnGap
Type: `number`\
Default: `0`
Size of the gap between an element's columns.
```glimmer-ts
A
B
// A B
```
##### rowGap
Type: `number`\
Default: `0`
Size of the gap between an element's rows.
```glimmer-ts
A
B
// A
//
// B
```
#### Flex
##### flexGrow
Type: `number`\
Default: `0`
See [flex-grow](https://css-tricks.com/almanac/properties/f/flex-grow/).
```glimmer-ts
Label:
Fills all remaining space
```
##### flexShrink
Type: `number`\
Default: `1`
See [flex-shrink](https://css-tricks.com/almanac/properties/f/flex-shrink/).
```glimmer-ts
Will be 1/4
Will be 3/4
```
##### flexBasis
Type: `number` `string`
See [flex-basis](https://css-tricks.com/almanac/properties/f/flex-basis/).
```glimmer-ts
X
Y
//=> 'X Y'
```
##### flexDirection
Type: `string`\
Allowed values: `row` `row-reverse` `column` `column-reverse`
See [flex-direction](https://css-tricks.com/almanac/properties/f/flex-direction/).
```glimmer-ts
X
Y
// X Y
X
Y
// Y X
X
Y
// X
// Y
```
##### flexWrap
Type: `string`\
Allowed values: `nowrap` `wrap` `wrap-reverse`
See [flex-wrap](https://css-tricks.com/almanac/properties/f/flex-wrap/).
```glimmer-ts
A
BC
// A
// B C
```
##### alignItems
Type: `string`\
Allowed values: `flex-start` `center` `flex-end`
See [align-items](https://css-tricks.com/almanac/properties/a/align-items/).
```glimmer-ts
X
ABC
// X A
// B
// C
```
##### alignSelf
Type: `string`\
Default: `auto`\
Allowed values: `auto` `flex-start` `center` `flex-end`
See [align-self](https://css-tricks.com/almanac/properties/a/align-self/).
```glimmer-ts
X
// X
//
//
```
##### justifyContent
Type: `string`\
Allowed values: `flex-start` `center` `flex-end` `space-between` `space-around` `space-evenly`
See [justify-content](https://css-tricks.com/almanac/properties/j/justify-content/).
```glimmer-ts
X
// [X ]
X
// [ X ]
X
// [ X]
```
#### Visibility
##### display
Type: `string`\
Allowed values: `flex` `none`\
Default: `flex`
Set this property to `none` to hide the element.
##### overflowX
Type: `string`\
Allowed values: `visible` `hidden`\
Default: `visible`
Behavior for an element's overflow in the horizontal direction.
##### overflowY
Type: `string`\
Allowed values: `visible` `hidden`\
Default: `visible`
Behavior for an element's overflow in the vertical direction.
##### overflow
Type: `string`\
Allowed values: `visible` `hidden`\
Default: `visible`
A shortcut for setting `overflowX` and `overflowY` at the same time.
#### Borders
##### borderStyle
Type: `string`\
Allowed values: `single` `double` `round` `bold` `singleDouble` `doubleSingle` `classic`
Add a border with a specified style.
If `borderStyle` is `undefined` (the default), no border will be added.
Ember TUI uses border styles from the [`cli-boxes`](https://github.com/sindresorhus/cli-boxes) module.
```glimmer-ts
single
double
round
bold
```
##### borderColor
Type: `string`
Change border color.
A shorthand for setting `borderTopColor`, `borderRightColor`, `borderBottomColor`, and `borderLeftColor`.
```glimmer-ts
Green Rounded Box
```
##### borderDimColor
Type: `boolean`\
Default: `false`
Dim the border color.
A shorthand for setting `borderTopDimColor`, `borderBottomDimColor`, `borderLeftDimColor`, and `borderRightDimColor`.
```glimmer-ts
Hello world
```
##### borderTop / borderRight / borderBottom / borderLeft
Type: `boolean`\
Default: `true`
Determines whether the respective border is visible.
#### Background
##### backgroundColor
Type: `string`
Background color for the element.
Accepts the same values as [`color`](#color) in the `` component.
```glimmer-ts
Red background
Orange background
```
The background color fills the entire `` area and is inherited by child `` components unless they specify their own `backgroundColor`.
### ``
Adds one or more newline (`\n`) characters.
Must be used within `` components.
#### count
Type: `number`\
Default: `1`
Number of newlines to insert.
```glimmer-ts
import { render, Text, Newline } from 'ember-tui';
const template =
Hello
World
;
render(template);
```
Output:
```
Hello
World
```
### ``
A flexible space that expands along the major axis of its containing layout.
It's useful as a shortcut for filling all the available space between elements.
For example, using `` in a `` with default flex direction (`row`) will position "Left" on the left side and will push "Right" to the right side.
```glimmer-ts
import { render, Box, Text, Spacer } from 'ember-tui';
const template =
Left
Right
;
render(template);
```
### ``
`` component permanently renders its output above everything else.
It's useful for displaying activity like completed tasks or logs - things that
don't change after they're rendered (hence the name "Static").
```glimmer-ts
import { render, Static, Box, Text } from 'ember-tui';
import { tracked } from '@glimmer/tracking';
class TestRunner {
@tracked tests = [];
constructor() {
let completedTests = 0;
const run = () => {
if (completedTests++ < 10) {
this.tests = [
...this.tests,
{
id: this.tests.length,
title: `Test #${this.tests.length + 1}`
}
];
setTimeout(run, 100);
}
};
run();
}
}
const runner = new TestRunner();
const template =
✔ {{test.title}}
Completed tests: {{runner.tests.length}}
;
render(template);
```
**Note:** `` only renders new items in the `items` array and ignores items
that were previously rendered.
#### items
Type: `Array`
Array of items of any type to render using the block you pass as component content.
### ``
Transform a string representation of components before they're written to output.
For example, you might want to apply a gradient to text or create some text effects.
**Note:** `` must be applied only to `` children components and shouldn't change the dimensions of the output; otherwise, the layout will be incorrect.
```glimmer-ts
import { render, Transform, Text } from 'ember-tui';
const template =
output.toUpperCase()}}>
Hello World
;
render(template);
```
Since the `transform` function converts all characters to uppercase, the final output rendered to the terminal will be "HELLO WORLD", not "Hello World".
#### transform(outputLine, index)
Type: `Function`
Function that transforms children output.
It accepts children and must return transformed children as well.
##### children
Type: `string`
Output of child components.
##### index
Type: `number`
The zero-indexed line number of the line that's currently being transformed.
## API
### render(tree, options?)
Mount a component and render the output.
#### tree
Type: `Component`
The root component to render.
#### options
Type: `object`
##### stdout
Type: `stream.Writable`\
Default: `process.stdout`
Output stream where the app will be rendered.
##### stdin
Type: `stream.Readable`\
Default: `process.stdin`
Input stream where the app will listen for input.
##### stderr
Type: `stream.Writable`\
Default: `process.stderr`
Error stream.
### startRender(document, options?)
Start the render loop for a document.
#### document
Type: `DocumentNode`
The document node to render.
#### options
Type: `object`
Same options as `render()`.
## Examples
Check out the [examples](ember-tui-demo/app/templates) directory for more examples:
- [Colors Demo](ember-tui-demo/app/templates/colors.gts) - Demonstrates text colors and styles
- [Box Layout Demo](ember-tui-demo/app/templates/box-demo.gts) - Shows flexbox layout capabilities
- [Static Component](ember-tui-demo/app/templates/static-test.gts) - Example of using Static component
- [Lorem Ipsum](ember-tui-demo/app/templates/lorem.gts) - Text wrapping and layout
## License
MIT