BlipGloss

https://github.com/wobsoriano/blipgloss
Admin
Blipgloss provides style definitions for creating visually appealing terminal layouts, powered by...
Tokens:2,182
Snippets:16
Trust Score:9.8
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install blipgloss

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Installs the blipgloss package using the Bun package manager.

```bash
bun add blipgloss
```

--------------------------------

### Basic Styling Example

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Demonstrates creating a new style with bold text, foreground and background colors, and padding, then rendering text with it.

```ts
import { NewStyle } from 'blipgloss'

const style = NewStyle()
  .Bold(true)
  .Foreground("#FAFAFA")
  .Background("#7D56F4")
  .PaddingTop(2)
  .PaddingLeft(4)
  .Width(22)

console.log(style.Render("Hello, bun."))
```

--------------------------------

### Trust blipgloss Dependency

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Marks blipgloss as a trusted dependency, which is necessary for Bun to download the correct binary.

```bash
bun pm trust blipgloss
```

--------------------------------

### Color Profiles

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Shows how to set background colors using different ANSI and True Color profiles, including adaptive colors for light/dark terminals and complete color specifications.

```js
// ANSI 16 colors (4-bit)
Background("5")  // magenta
Background("9")  // red
Background("12") // light blue

// ANSI 256 colors (8-bit)
Background("86")  // aqua
Background("201") // hot pink
Background("202") // orange

// True Color (16,777,216 colors; 24-bit)
Background("#0000FF") // good ol' 100% blue
Background("#04B575") // a green
Background("#3C3C3C") // a dark gray

// Adaptive Colors (for light and dark backgrounds)
Background({
  Light: '236',
  Dark: '248'
})

// Complete Colors (specifies values for True, ANSI256, and ANSI profiles)
Background({
  True: "#0000FF",
  ANSI256: "86",
  ANSI: "5"
})

// Complete Adaptive Colors (specifies exact values for light/dark backgrounds across profiles)
Background({
  Light: {TrueColor: "#d7ffae", ANSI256: "193", ANSI: "11"},
  Dark: {TrueColor: "#d75fee", ANSI256: "163", ANSI: "5"}
})
```

--------------------------------

### Copy Styles with Copy()

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Demonstrates how to create a true, dereferenced copy of a style object using the `Copy()` method. This prevents unintended mutation of original styles when modifying a copied instance.

```js
const style = NewStyle().Foreground("219")

const wildStyle = style.Copy().Blink(true)
```

--------------------------------

### Block-Level Formatting (Padding & Margins)

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Demonstrates setting padding and margins for text blocks, including individual sides and shorthand CSS-like syntax.

```js
// Padding
const style = NewStyle()
  .PaddingTop(2)
  .PaddingRight(4)
  .PaddingBottom(2)
  .PaddingLeft(4)

// Margins
const style = NewStyle()
  .MarginTop(2)
  .MarginRight(4)
  .MarginBottom(2)
  .MarginLeft(4)

// Shorthand syntax for padding (all sides)
NewStyle().Padding(2)

// Shorthand syntax for margin (top/bottom, left/right)
NewStyle().Margin(2, 4)

// Shorthand syntax for padding (top, sides, bottom)
NewStyle().Padding(1, 4, 2)

// Shorthand syntax for margin (clockwise: top, right, bottom, left)
NewStyle().Margin(2, 4, 3, 1)
```

--------------------------------

### Render Styled Text

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Shows the basic usage of the `Render(string)` method to apply the defined styles to a given string and produce the final styled output for terminal display.

```js
console.log(NewStyle().Bold(true).Render("Hello, bun."))
```

--------------------------------

### Enforce Layout with Inline, MaxWidth, MaxHeight

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Explains how to enforce specific rendering behaviors using `Inline(true)`, `MaxWidth(n)`, and `MaxHeight(n)`. These methods control whether text wraps, and limit its dimensions to ensure predictable UI components.

```js
// Force rendering onto a single line, ignoring margins, padding, and borders.
someStyle.Inline(true).Render("yadda yadda")

// Also limit rendering to five cells
someStyle.Inline(true).MaxWidth(5).Render("yadda yadda")

// Limit rendering to a 5x5 cell block
someStyle.MaxWidth(5).MaxHeight(5).Render("yadda yadda")
```

--------------------------------

### Measure Width and Height of Text Blocks

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Explains how to use the `Width()` and `Height()` utility functions to determine the actual rendered dimensions of a styled text block. This is crucial for complex layout calculations.

```js
import { NewStyle, Width, Height } from 'blipgloss'

const block = NewStyle()
  .Width(40)
  .Padding(2)
  .Render(someLongString)

// Get the actual, physical dimensions of the text block.
const width = Width(block)
const height = Height(block)
```

--------------------------------

### Width and Height

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Sets the minimum width and height for a styled text element.

```ts
const str = NewStyle()
  .Width(24)
  .Height(32)
  .Foreground("63")
  .Render("What’s for lunch?")
```

--------------------------------

### Inline Formatting Options

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Applies various inline text formatting styles such as bold, italic, faint, blink, strikethrough, underline, and reverse.

```js
const style = NewStyle()
  .Bold(true)
  .Italic(true)
  .Faint(true)
  .Blink(true)
  .Strikethrough(true)
  .Underline(true)
  .Reverse(true)
```

--------------------------------

### Place Text in Whitespace

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Covers the `PlaceHorizontal`, `PlaceVertical`, and `Place` utility functions for positioning text within a defined whitespace area. These functions allow centering, aligning to edges, and placing text in specific corners.

```js
import { PlaceHorizontal, PlaceVertical, Place, Position } from 'blipgloss'

// Center a paragraph horizontally in a space 80 cells wide. The height of
// the block returned will be as tall as the input paragraph.
const block = PlaceHorizontal(80, Position.Center, fancyStyledParagraph)

// Place a paragraph at the bottom of a space 30 cells tall. The width of
// the text block returned will be as wide as the input paragraph.
const block = PlaceVertical(30, Position.Bottom, fancyStyledParagraph)

// Place a paragraph in the bottom right corner of a 30x80 cell space.
const block = Place(30, 80, Position.Right, Position.Bottom, fancyStyledParagraph)
```

--------------------------------

### Unset Styling Rules

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Illustrates how to remove previously applied style rules using methods like `UnsetBold()` and `UnsetBackground()`. This allows for dynamic modification of styles, reverting specific attributes.

```js
const style = NewStyle().
    Bold(true).                        // make it bold
    UnsetBold().                       // jk don't make it bold
    Background("227"). // yellow background
    UnsetBackground()                  // never mind
```

--------------------------------

### Border Styling

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Applies various border styles, including predefined shapes, colors, and custom border characters for different sides.

```ts
import { NewStyle, Border } from 'blipgloss'

// Add a purple, rectangular border
const style = NewStyle()
  .BorderStyle(Border.Normal)
  .BorderForeground("63")

// Set a rounded, yellow-on-purple border to the top and left
const anotherStyle = NewStyle()
  .BorderStyle(Border.Rounded)
  .BorderForeground("228")
  .BorderBackground("63")
  .BorderTop(true)
  .BorderLeft(true)

// Make your own border with custom characters
const style = NewStyle()
  .BorderStyle({
    Top:         "._.:*:",
    Bottom:      "._.:*:",
    Left:        "|*",
    Right:       "|*",
    TopLeft:     "*",
    TopRight:    "*",
    BottomLeft:  "*",
    BottomRight: "*"
  })
```

--------------------------------

### Join Paragraphs Horizontally and Vertically

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Details the utility functions `JoinHorizontal` and `JoinVertical` for assembling text blocks. These functions allow precise alignment and spacing when combining multiple styled paragraphs.

```js
import { Position, JoinHorizontal, JoinVertical } from 'blipgloss'

// Horizontally join three paragraphs along their bottom edges
JoinHorizontal(Position.Bottom, paragraphA, paragraphB, paragraphC)

// Vertically join two paragraphs along their center axes
JoinVertical(Position.Center, paragraphA, paragraphB)

// Horizontally join three paragraphs, with the shorter ones aligning 20%
// from the top of the tallest
JoinHorizontal(0.2, paragraphA, paragraphB, paragraphC)
```

--------------------------------

### Text Alignment

Source: https://github.com/wobsoriano/blipgloss/blob/main/README.md

Sets the horizontal alignment of text within its container to left, right, or center.

```ts
import { Position } from 'blipgloss'

const style = NewStyle()
  .Width(24)
  .Align(Position.Left)   // align it left
  .Align(Position.Right)  // no wait, align it right
  .Align(Position.Center) // just kidding, align it in the center
```
Tokens:
Raw