{"id":13819883,"url":"https://github.com/piotrmurach/tty-box","last_synced_at":"2025-05-16T09:07:16.541Z","repository":{"id":42596685,"uuid":"140947800","full_name":"piotrmurach/tty-box","owner":"piotrmurach","description":"Draw various frames and boxes in your terminal window","archived":false,"fork":false,"pushed_at":"2022-07-16T04:45:01.000Z","size":213,"stargazers_count":188,"open_issues_count":5,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-09T21:47:46.544Z","etag":null,"topics":["border","box-drawing","boxplot","console","frame","ruby","rubygem","terminal","terminal-graphics","tty"],"latest_commit_sha":null,"homepage":"http://ttytoolkit.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piotrmurach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"piotrmurach"}},"created_at":"2018-07-14T13:20:30.000Z","updated_at":"2025-04-19T21:16:48.000Z","dependencies_parsed_at":"2022-08-30T23:21:52.266Z","dependency_job_id":null,"html_url":"https://github.com/piotrmurach/tty-box","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-box/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501558,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["border","box-drawing","boxplot","console","frame","ruby","rubygem","terminal","terminal-graphics","tty"],"created_at":"2024-08-04T08:00:54.461Z","updated_at":"2025-05-16T09:07:11.525Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":["Happy Exploring 🤘","Ruby"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://ttytoolkit.org\"\u003e\u003cimg width=\"130\" src=\"https://github.com/piotrmurach/tty/blob/master/images/tty.png\" alt=\"TTY Toolkit logo\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# TTY::Box [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]\n\n[![Gem Version](https://badge.fury.io/rb/tty-box.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-box/workflows/CI/badge.svg?branch=master)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/h9b88fk5xpya3fh1?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/dfac05073e1549e9dbb6/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-box/badge.svg)][coverage]\n[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-box.svg?branch=master)][inchpages]\n\n[gitter]: https://gitter.im/piotrmurach/tty\n[gem]: http://badge.fury.io/rb/tty-box\n[gh_actions_ci]: https://github.com/piotrmurach/tty-box/actions?query=workflow%3ACI\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-box\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-box/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-box\n[inchpages]: http://inch-ci.org/github/piotrmurach/tty-box\n\n\u003e Draw various frames and boxes in the terminal window.\n\n**TTY::Box** provides box drawing component for [TTY](https://github.com/piotrmurach/tty) toolkit.\n\n![Box drawing](https://github.com/piotrmurach/tty-box/blob/master/assets/tty-box-drawing.png)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"tty-box\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install tty-box\n\n## Contents\n\n* [1. Usage](#1-usage)\n* [2. Interface](#2-interface)\n  * [2.1 frame](#21-frame)\n  * [2.2 position](#22-position)\n  * [2.3 dimension](#23-dimension)\n  * [2.4 title](#24-title)\n  * [2.5 border](#25-border)\n  * [2.6 styling](#26-styling)\n  * [2.7 formatting](#27-formatting)\n  * [2.8 messages](#28-messages)\n    * [2.8.1 info](#281-info)\n    * [2.8.2 warn](#282-warn)\n    * [2.8.3 success](#283-success)\n    * [2.8.4 error](#284-error)\n\n## 1. Usage\n\nUsing the `frame` method, you can draw a box in a terminal emulator:\n\n```ruby\nbox = TTY::Box.frame \"Drawing a box in\", \"terminal emulator\", padding: 3, align: :center\n```\n\nAnd then print:\n\n```ruby\nprint box\n# =\u003e\n# ┌───────────────────────┐\n# │                       │\n# │                       │\n# │                       │\n# │   Drawing a box in    │\n# │   terminal emulator   │\n# │                       │\n# │                       │\n# │                       │\n# └───────────────────────┘\n```\n\n## 2. Interface\n\n### 2.1 frame\n\nYou can draw a box in your terminal window by using the `frame` method and passing a content to display. By default the box will be drawn around the content.\n\n```ruby\nprint TTY::Box.frame \"Hello world!\"\n# =\u003e\n# ┌────────────┐\n# │Hello world!│\n# └────────────┘\n```\n\nYou can also provide multi line content as separate arguments.\n\n```ruby\nprint TTY::Box.frame \"Hello\", \"world!\"\n# =\u003e\n# ┌──────┐\n# │Hello │\n# │world!│\n# └──────┘\n```\n\nAlternatively, provide a multi line content using newline chars in a single argument:\n\n```ruby\nprint TTY::Box.frame \"Hello\\nworld!\"\n# =\u003e\n# ┌──────┐\n# │Hello │\n# │world!│\n# └──────┘\n```\n\nFinally, you can use a block to specify content:\n\n```ruby\nprint TTY::Box.frame { \"Hello world!\" }\n# =\u003e\n# ┌────────────┐\n# │Hello world!│\n# └────────────┘\n```\n\nYou can also enforce a given box size without any content and use [tty-cursor](https://github.com/piotrmurach/tty-cursor) to position content whatever you like.\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10)\n```\n\nWhen printed will produce the following output in your terminal:\n\n```ruby\nprint box\n# =\u003e\n# ┌────────────────────────────┐\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# └────────────────────────────┘\n```\n\nAlternatively, you can also pass a block to provide a content for the box:\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10) do\n  \"Drawin a box in terminal emulator\"\nend\n```\n\nWhen printed will produce the following output in your terminal:\n\n```ruby\nprint box\n# =\u003e\n# ┌────────────────────────────┐\n# │Drawing a box in terminal   │\n# │emulator                    │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# └────────────────────────────┘\n```\n\n### 2.2 position\n\nBy default, a box will not be positioned. To position your box absolutely within a terminal window use `:top` and `:left` keyword arguments:\n\n```ruby\nTTY::Box.frame(top: 5, left: 10)\n```\n\nThis will place box 10 columns to the right and 5 lines down counting from the top left corner.\n\nIf you wish to center your box within the terminal window then consider using [tty-screen](https://github.com/piotrmurach/tty-screen) for gathering terminal screen size information.\n\n### 2.3 dimension\n\nAt the very minimum a box requires to be given size by using two keyword arguments `:width` and `:height`:\n\n```ruby\nTTY::Box.frame(width: 30, height: 10)\n```\n\nIf you wish to create a box that depends on the terminal window size then consider using [tty-screen](https://github.com/piotrmurach/tty-screen) for gathering terminal screen size information.\n\nFor example to print a box that spans the whole terminal window do:\n\n```ruby\nTTY::Box.frame(width: TTY::Screen.width, height: TTY::Screen.height)\n```\n\n### 2.4 title\n\nYou can specify titles using the `:title` keyword and a hash value that contains one of the `:top_left`, `:top_center`, `:top_right`, `:bottom_left`, `:bottom_center`, `:bottom_right` keys and actual title as value. For example, to add titles to top left and bottom right of the frame do:\n\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10, title: {top_left: \"TITLE\", bottom_right: \"v1.0\"})\n```\n\nwhich when printed in console will render the following:\n\n```ruby\nprint box\n# =\u003e\n# ┌TITLE───────────────────────┐\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# └──────────────────────(v1.0)┘\n```\n\n### 2.5 border\n\nThere are three types of border `:ascii`, `:light`, `:thick`. By default the `:light` border is used. This can be changed using the `:border` keyword:\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10, border: :thick)\n```\n\nand printing the box out to console will produce:\n\n```ruby\nprint box\n# =\u003e\n# ╔════════════════════════════╗\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ║                            ║\n# ╚════════════════════════════╝\n```\n\nYou can also selectively specify and turn off border parts by passing a hash with a `:border` key. The border parts are:\n\n```\n                 :top\n    :top_left ┌────────┐ :top_right\n              │        │\n        :left │        │ :right\n              │        │\n :bottom_left └────────┘ :bottom_right\n               :bottom\n```\n\nThe following are available border parts values:\n\n| Border values        | ASCII | Unicode Light | Unicode Thick |\n| -------------------- |:-----:|:-------------:|:-------------:|\n| :line                | `-`   | `─`           | `═`           |\n| :pipe                | `\\|`  | `\\│`          | `\\║`          |\n| :cross               | `+`   | `┼`           | `╬`           |\n| :divider_up          | `+`   | `┴`           | `╩`           |\n| :divider_down        | `+`   | `┬`           | `╦`           |\n| :divider_left        | `+`   | `┤`           | `╣`           |\n| :divider_right       | `+`   | `├`           | `╠`           |\n| :corner_top_left     | `+`   | `┌`           | `╔`           |\n| :corner_top_right    | `+`   | `┐`           | `╗`           |\n| :corner_bottom_left  | `+`   | `└`           | `╚`           |\n| :corner_bottom_right | `+`   | `┘`           | `╝`           |\n\nFor example, to change all box corners to be a `:cross` do:\n\n```ruby\nbox = TTY::Box.frame(\n  width: 10, height: 4,\n  border: {\n    top_left: :cross,\n    top_right: :cross,\n    bottom_left: :cross,\n    bottom_right: :cross\n  }\n)\n```\n\n```ruby\nprint box\n# =\u003e\n# ┼────────┼\n# │        │\n# │        │\n# ┼────────┼\n```\n\nIf you want to remove a given border element as a value use `false`. For example to remove bottom border do:\n\n```ruby\nTTY::Box.frame(\n  width: 30, height: 10,\n  border: {\n    type: :thick,\n    bottom: false\n  })\n```\n\n### 2.6 styling\n\nBy default drawing a box doesn't apply any styling. You can change this using the `:style` keyword with foreground `:fg` and background `:bg` keys for both the main content and the border:\n\n```ruby\nstyle: {\n  fg: :bright_yellow,\n  bg: :blue,\n  border: {\n    fg: :bright_yellow,\n    bg: :blue\n  }\n}\n```\n\nThe above style configuration will produce the result similar to the top demo, a MS-DOS look \u0026 feel window.\n\nYou can disable or force output styling regardless of the terminal using the `enable_color` keyword. By default, the color support is automatically detected.\n\n```ruby\nTTY::Box.frame({\n  enable_color: true, # force to always color output\n  style: {\n    border: {\n      fg: :bright_yellow,\n      bg: :blue\n    }\n  }\n})\n```\n\n### 2.7 formatting\n\nYou can use `:align` keyword to format content either to be `:left`, `:center` or `:right` aligned:\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10, align: :center) do\n  \"Drawing a box in terminal emulator\"\nend\n```\n\nThe above will create the following output in your terminal:\n\n```ruby\nprint box\n# =\u003e\n# ┌────────────────────────────┐\n# │ Drawing a box in terminal  │\n# │          emulator          │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# │                            │\n# └────────────────────────────┘\n```\n\nYou can also use `:padding` keyword to further format the content using the following values:\n\n```ruby\n[1,3,1,3]  # =\u003e pad content left \u0026 right with 3 spaces and add 1 line above \u0026 below\n[1,3]      # =\u003e pad content left \u0026 right with 3 spaces and add 1 line above \u0026 below\n1          # =\u003e shorthand for [1,1,1,1]\n```\n\nFor example, if you wish to pad content all around do:\n\n```ruby\nbox = TTY::Box.frame(width: 30, height: 10, align: :center, padding: 3) do\n  \"Drawing a box in terminal emulator\"\nend\n```\n\nHere's an example output:\n\n```ruby\nprint box\n# =\u003e\n# ┌────────────────────────────┐\n# │                            │\n# │                            │\n# │                            │\n# │     Drawing a box in       │\n# │     terminal emulator      │\n# │                            │\n# │                            │\n# │                            │\n# └────────────────────────────┘\n#\n```\n\n### 2.8 messages\n\n![Box messages](https://github.com/piotrmurach/tty-box/blob/master/assets/tty-box-messages.png)\n\n#### 2.8.1 info\n\nTo draw an information type box around your content use `info`:\n\n```ruby\nbox = TTY::Box.info(\"Deploying application\")\n```\n\nAnd then print:\n\n```ruby\nprint box\n# =\u003e\n# ╔ ℹ INFO ═══════════════╗\n# ║                       ║\n# ║ Deploying application ║\n# ║                       ║\n# ╚═══════════════════════╝\n```\n\n#### 2.8.2 warn\n\nTo draw a warning type box around your content use `warn`:\n\n```ruby\nbox = TTY::Box.warn(\"Deploying application\")\n```\n\nAnd then print:\n\n```ruby\nprint box\n# =\u003e\n# ╔ ⚠ WARNING ════════════╗\n# ║                       ║\n# ║ Deploying application ║\n# ║                       ║\n# ╚═══════════════════════╝\n```\n\n#### 2.8.3 success\n\nTo draw a success type box around your content use `success`:\n\n```ruby\nbox = TTY::Box.success(\"Deploying application\")\n```\n\nAnd then print:\n\n```ruby\nprint box\n# =\u003e\n# ╔ ✔ OK ═════════════════╗\n# ║                       ║\n# ║ Deploying application ║\n# ║                       ║\n# ╚═══════════════════════╝\n```\n\n#### 2.8.4 error\n\nTo draw an error type box around your content use `error`:\n\n```ruby\nbox = TTY::Box.error(\"Deploying application\")\n```\n\nAnd then print:\n\n```ruby\nprint box\n# =\u003e\n# ╔ ⨯ ERROR ══════════════╗\n# ║                       ║\n# ║ Deploying application ║\n# ║                       ║\n# ╚═══════════════════════╝\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-box. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/piotrmurach/tty-box/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Box project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-box/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2018 Piotr Murach. See LICENSE for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-box/lists"}