Quick-Start Guide

Welcome to the quick-start guide! (Well, it’s more of a formal documentation)

We will go through and explain each element of framed_text, from simple frames to complex data structures and progress bars!

More specifically, this guide will cover:

• framed_text.FramedText

• framed_text.LabeledData

• framed_text.Status

• framed_text.FramedHeader

• framed_text.ShortenText

• framed_text.ProgressBar

• framed_text.Spinner

Important

Make sure to import the module first!

from framed_text import FramedText, LabeledData, Status, ... # Any other items you need

Adding Frames around Text

The basic parameters for FramedText include:

• framed_color: The color of the frame

• title: The title of the frame

• title_color: The color of the title

• attrs: The attributes of the title

• text: The text to display

We’ll go over each of these parameters in detail.

Creating a Simple Frame with Text

You can create a simple frame using the following code:

Using the FramedText class

ft: FramedText = FramedText(
  text=[
    "Hello world"
  ]
)
print(ft)

We can add more text by adding more strings to the text list:

Multiple lines can be added to the text list

ft: FramedText = FramedText(
  text=[
    "Hello world",
    "Another line",
    "Another Another line"
  ]
)
print(ft)

Styling the Frame and Adding a Title

You can color the frame using the framed_color parameter:

Coloring the frame red

ft: FramedText = FramedText(
  frame_color="red",
  text=[
    "Hello world"
  ]
)
print(ft)

You can add a title to the frame using the title parameter:

A simple title for the frame

ft: FramedText = FramedText(
  title="This is a title",
  frame_color="red",
  text=[
    "Hello world"
  ]
)
print(ft)

To color the title, use title_color:

Coloring the title green. Note that the frame color is still red.

ft: FramedText = FramedText(
  title="This is a title",
  frame_color="red",
  title_color="green",
  text=[
    "Hello world"
  ]
)
print(ft)

The title supports termcolor’s formatting options using attrs parameter:

Applying a bold and underline style to the title. The title color is still green.

ft: FramedText = FramedText(
  title="This is a title",
  frame_color="red",
  title_color="green",
  attrs=["bold", "underline"],
  text=[
    "Hello world"
  ]
)
print(ft)

Advanced Parameters

In addition to the above parameters, FramedText also features:

• cutoff: If true, will cut off text if it exceeds the terminal width

• mode: Determines how text is cut off. Used with cutoff

• allow_ansi: If true, will allow ANSI codes to be displayed. By default, this is false for reasons we’ll get to.

• center_text: If true, will center the text display to the middle of the frame.

Added in version 2026.06.03.18.00:

• frame_size: Determines how the frame is rendered. See frame_size for more information.

mode

Changed in version 2026.05.04.17.15: mode now applies to all str objects in the text parameter, not just LabeledData and Status objects.

mode can be one of the following:

• "char": Cut off the line based on which character surpasses the terminal width

• "word": Cut off the line based on which character surpasses the terminal width

• "middle": Trim the middle of the line until it fits the terminal width

Below are examples of each mode:

When mode is set to "char"

"The quick brown fox jumped ove…"

When mode is set to "word"

"The quick brown fox jumped…"

When mode is set to "middle"

"The quick brown…the lazy dog"

Note

LabeledData.Path behaves differently when mode is set to "word".

Parts of the path will be cut and replaced with an ellipsis if the path exceeds the limit:

• "/home/user/path/to/a/file.txt" becomes "/home/user/path/…/file.text"

allow_ansi

This parameter is present due to the way cutoff works.

termcolor formatted strings contain ANSI codes (e.g. \x1b[31m for red). Normally, this wouldn’t be an issue, however, when cutoff is enabled, there is the issue of the ANSI codes being cut off, which could mess up the display of the framed text.

Because of this, any strings containing ANSI codes will have their codes removed! The only exceptions are for the objects provided by framed_text (e.g. Status and LabeledData).

However, if you want to allow ANSI codes to be displayed, you can set allow_ansi to true.

frame_size

Added in version 2026.06.03.18.00.

This parameter controls how the frame is rendered. It has the following options:

• "full": The default mode. Frame size is based on terminal width

ft: FramedText = FramedText(
    title="Frame Size",
    frame_color="blue",
    text=[
        "A plain string",
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
            suffix="with a suffix"
        ),
        Status.Info(msg="An info message"),
    ]
)
print(ft)

• "dynamic": Frame size is based on text length

ft: FramedText = FramedText(
    title="Frame Size",
    frame_color="blue",
    frame_size="dynamic",
    text=[
        "A plain string",
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
            suffix="with a suffix"
        ),
        Status.Info(msg="An info message"),
    ]
)
print(ft)

When using center_text in conjunction with "dynamic", the entire frame will be centered.

ft: FramedText = FramedText(
    title="Frame Size",
    frame_color="blue",
    center_text=True,
    frame_size="dynamic",
    text=[
        "A plain string",
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
            suffix="with a suffix"
        ),
        Status.Info(msg="An info message"),
    ]
)
print(ft)

Data with Labels

To add data to the text with a label, it’s recommended to use LabeledData.

LabeledData is a collection of typed objects that can be used to display data in a frame.

Each class of LabeledData has the following base parameters:

• label: A label to assign to the text

• value: The value to display

• quotes: Whether to add quotes around the value

Added in version 2026.05.15.14.30: Added LabeledData.Date

Added in version 2026.05.21.16.30:

• Added LabeledData.Bytes

• Changed default colors for LabeledData.Number and LabeledData.Date

Changed in version 2026.04.03.16.00: Used to be color and attrs.

• val_color: The color for the value [1].

• val_attrs: The attribute(s) for the value [2].

Added in version 2026.04.03.16.00:

• label_color: The color for the label [1].

• label_attrs: The attribute(s) for the label [2].

• colon_match: If true, label_color and label_attrs will be applied to the colon.

Added in version 2026.05.03.14.45:

• no_colon: If true, the colon will be omitted from the text. Overrides colon_match

All LabeledData classes using colon_match

ft: FramedText = FramedText(
text=[
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
            no_colon=True
        ),
        LabeledData.Number(
            label="LabeledData.Number",
            value=3.14159,
            no_colon=True
        ),
        LabeledData.Boolean(
            label="LabeledData.Boolean",
            value=True,
            no_colon=True
        ),
        LabeledData.Path(
            label="LabeledData.Path",
            value=Path("/path/to/a/file.txt"),
            no_colon=True
        ),
        LabeledData.Date(
            label="LabeledData.Date",
            no_colon=True
        ),
        LabeledData.Bytes(
            label="LabeledData.Bytes",
            value=65535,
            no_colon=True
        ),
    ]
)
print(ft)

---

Added suffix support to each type of LabeledData. Suffixes will appear after the value. The following parameters apply to the suffix:

• suffix: Optional text to appear after the value

• suffix_color: The color for the suffix [1].

• suffix_attrs: The attribute(s) for the suffix [2].

Note

The cut-off mode for suffixes is always "word". See mode for more information.

All LabeledData classes with suffixes

ft: FramedText = FramedText(
text=[
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
            suffix="with a suffix"
        ),
        LabeledData.Number(
            label="LabeledData.Number",
            value=3.14159,
            suffix="with a suffix"
        ),
        LabeledData.Boolean(
            label="LabeledData.Boolean",
            value=True,
            suffix="with a suffix"
        ),
        LabeledData.Path(
            label="LabeledData.Path",
            value=Path("/path/to/a/file.txt"),
            suffix="with a suffix"
        ),
        LabeledData.Date(
            label="LabeledData.Date",
            suffix="with a suffix"
        ),
        LabeledData.Bytes(
            label="LabeledData.Bytes",
            value=65535,
            suffix="with a suffix"
        ),
    ]
)
print(ft)

Below lists the classes with additional parameters or those that differ from the base parameters:

LabeledData.Number

• round_to: Number of decimal places to round to

• leading_zeros: Number of leading zeros to add

• int_no_round: Whether to display the value as an integer without rounding

LabeledData.Boolean

This class splits text and color across seperate parameters for True and False values.

• t_text: Text to display when the value is True

• f_text: Text to display when the value is False

• t_color: Color to use when the value is True

• f_color: Color to use when the value is False

LabeledData.Date

• strftime: Date formatter for when value is a datetime object or value is not passed

LabeledData.Bytes

• show_unit: Whether to show the unit (e.g. “KiB”) and convert the bytes. If False, will show the raw bytes.

• unit_type: "iec" uses the IEC format (e.g. “KiB” -> Kibibytes), "si" uses the SI format (e.g. “KB” -> Kilobytes)

• unit_match: If True, the unit will match the styling of the value

• unit_color: The color of the unit [1] [4]

• unit_attrs: The attribute(s) of the unit [2] [4]

The following LabeledData types are supported:

Class	Supported Types
LabeledData.String	str
LabeledData.Number	int, float
LabeledData.Boolean	bool
LabeledData.Path	pathlib.Path
LabeledData.Date	datetime.datetime, str
LabeledData.Bytes	int

Here is an example of using LabeledData to display a string value:

Using the LabeledData class with FramedText

ft: FramedText = FramedText(
    text=[
        LabeledData.String(
            label="LabeledData.String",
            value="A String value",
        )
    ]
)
print(ft)

Ouptut of all of the LabeledData types printed together

Displaying Statuses

framed_text also features Status objects to display messages with a status icon.

Status takes the following parameters:

• icon: The icon to display

• icon_color: The color of the icon

• sep: The seperator between the icon and message

• msg: The message to display

• text_color: The color of the message

Added in version 2026.05.09.14.45:

• overwrite: If true, will overwrite the previous line with the new status

The Status is constructed as: <icon><sep><message>

Changed in version 2026.04.04.14.00:

• If the icon is an empty string, the seperator will not be displayed.

• The Status will be constructed as: <message>

• text_color will still be applied to msg

---

The default Status format is: <I>: <message>

Below is a full list of each Status and their default output:

Added in version 2026.04.29.16.30: Added Status.Hidden

Each status is printed on a new line. Note that some messages are colored.

ft: FramedText = FramedText(
  title="Status",
  frame_color="red",
  text=[
    Status.Info(msg="This is an info message"),
    Status.Action(msg="This is an action message"),
    Status.Success(msg="This is a success message"),
    Status.Warn(msg="This is a warning message"),
    Status.Fail(msg="This is a fail message")

    # You can omit the 'msg=' parameter and achieve the same result
    Status.Hidden("This is a hidden message. It just makes the text darker.")
  ]
)
print(ft)

Displaying a Header and Divider

FramedHeader is like FramedText, but it only displays a single line of the ‘frame’:

A basic FramedHeader. Without arguments, this is effectively a divider.

fh: FramedHeader = FramedHeader()

Like FramedText, we can color the header:

Coloring the ‘divider’ red

fh: FramedHeader = FramedHeader(
  frame_color="red"
)

Currently, this ‘header’ is more of a divider. To actually make it a header and add a title, we can add:

Adding a title makes it a header

fh: FramedHeader = FramedHeader(
  title="Header",
  frame_color="red"
)

FrameHeader also supports the same title formatting as FramedText:

Same example as FramedText, but adapted for FramedHeader

fh: FramedHeader = FramedHeader(
  title="Header",
  frame_color="red",
  title_color="green",
  attrs=["bold", "underline"]
)

Shortening Text

Added in version 2026.05.04.17.15: Added ShortenText

ShortenText allows for shortening a string to a specified length. The main parameters are:

• text: The string to shorten

• limit: The maximum length of the string

• mode: The mode to use for shortening

By default, if no limit is provided, the string will be shortened to the width of the terminal using os.get_terminal_size().columns.

The mode behaves the same as FramedText’s mode parameter. See mode for more information.

The text parameter currently supports the following types:

• str objects

• Any LabeledData object [3]

• Any Status object [3]

ShortenText can be used on its own or in other classes, such as FramedText.

ShortenText used on its own

text: str = "This is a very long message that should be cut off at some point. Ideally, this should be cut off earlier than later."
short_text = ShortenText(text=text)

# Or for a direct str type:
# short_text: str = ShortenText(text=text).__str__()
# short_text: str = ShortenText(text=text).text_shorten

print(short_text)

ShortenText used with FramedText. Notice the use of mode="word"

line: str = "This is a very long message that should be cut off at some point. Ideally, this should be cut off earlier than later."
text: list = [
    ShortenText(text=line)
]
ft: FramedText = FramedText(
    title="Shorten Text",
    text=text,
    frame_color="red",
    mode="word"
)
print(ft)

str objects in the text list parameter of FramedText will use ShortenText to shorten strings, so no need to use ShortenText directly on them!

text: list = [
    "This is a very long message that should be cut off at some point. Ideally, this should be cut off earlier than later."
]
ft: FramedText = FramedText(
    title="Shorten Text built-in to FramedText",
    text=text,
    frame_color="blue",
    mode="middle"
)
print(ft)

Creating a Progress Bar

Added in version 2026.05.09.14.45: Added ProgressBar

Progress bars can be created using the ProgressBar class. This will create a progress bar that snaps to the bottom of the terminal. It will look something like this:

A basic progress bar with value=3 and total=10

ProgressBar takes a few parameters, however not all of them are required.

Required Parameters

• value: The current value

• total: The total value

Data Parameters

• show_percent: If true, will display the percentage of the progress bar (value / total)

• show_values: If true, will display the current value and total value formatted as "<value>/<total>"

Customization Parameters

• label: A text label for the progress bar

• show_frame: If true, will display a frame around the progress bar, just like FramedText

• progress_icon: The icon to use for the progress bar

• empty_icon: The icon to use for the empty space in the progress bar

• brackets: The brackets to use for the progress bar. The input is formatted as (<left>, <right>)

Color Parameters [1]

• value_color: Color of the label

• label_color: Color of the label

• percent_color: Color of the percentage

• progress_color: Color of the progress display

• brackets_color: Color of the brackets

• frame_color: Color of the frame

Other Parameters

• safe_mode: If true, will clear the terminal and move cursor to top to ensure room for progress bar and any other data.

• skip_init: If true, will only initialize when display or update_progress is called

The Basics of Creating a Progress Bar

The basic setup for a working progress bar looks something like this:

from time import sleep
try:
    val = 0
    total = 100
    pb: ProgressBar = ProgressBar(
        value=val,
        total=total,
    )
    # Loop can iterate over anything
    for i in range(total):
        # This is where code for doing stuff goes
        # ...
        # Update the progress
        pb.update_progress(value=i+1)
        sleep(0.1)
    pb.reset()
except (EOFError, KeyboardInterrupt):
    ProgressBar.force_reset(show_frame=False, label=False)

This is a lot, so let’s break it down:

• First, we define our ProgressBar. Here, we are just passing values to the value and total parameters.

• Next, we loop over the total value and update the value of the progress bar with i+1. This will increment the progress bar by 1.

• After the loop, we call reset to reset the terminal back to the state before the progress bar was displayed. We have to do this otherwise we won’t be able to reach the bottom lines of our terminal.

Now, the try-except block is in case there is an error in the program while the progress bar is running. Without it, we would have the same issue as if we omitted the pb.reset() call. The (EOFError, KeyboardInterrupt) used are for demonstration, but you can use any exception you want.

Warning

The parameters for ProgressBar.force_reset MUST match the parameters for ProgressBar. Otherwise, unexpected results may occur.

The 2 parameters needed are:

• show_frame: Same as ProgressBar

• label: Set this to True if a label was used for the ProgressBar. Otherwise, leave it False

A more advanced example looks something like this:

Notice the params in ProgressBar.force_reset matches the params in pb

from time import sleep
try:
    val = 0
    total = 50
    print(Status.Action("Batch processing information..."))
    pb: ProgressBar = ProgressBar(
        value=val,
        total=total,
        label="Test Progress Bar",
        show_percent=True,
        show_frame=True,
        frame_color="blue",
        progress_icon='|',
        empty_icon=' ',
    )
    for i in range(total):
        print(Status.Hidden(icon='>>', msg=f"Processing file-{i+1}.txt..."))
        pb.update_progress(value=i+1)
        sleep(0.1)
        print(Status.Hidden(icon='>>', msg=f"Processed file-{i+1}.txt", overwrite=True))
    pb.reset()
    print(Status.Success("Batch processing complete!"))
except (EOFError, KeyboardInterrupt):
    ProgressBar.force_reset(show_frame=True, label=True)

Here, we are printing a status message each iteration. These print statements will not overwrite the progress bar as when ProgressBar is initialized, it will change the scrollable region of the terminal to exclude the progress bar.

We also customized the appearance of the progress bar, so it now looks something like this:

A full run of the above example looks like this:

Important Notes

ProgressBar is designed to be used on its own, not in any other class within framed_text.

Additionally, it is important to call reset on the progress bar when you are done with it. Not doing so may lead to unexpected behavior.

Currently, the progress bar does not handle resizing of the terminal window. Avoid resizing the window while the progress bar is running.

Creating a Spinner

Added in version 2026.05.12.17.00: Added Spinner class

Spinners are similar to progress bars, but don’t show any information by themselves. However, the Spinner class can accept text to display next to the spinner.

Spinner takes the following parameters:

• text: Text to display next to the spinner. Omit for no text.

• icons_id: ID string of one of the built-in icon sets.

• done_icon: Icon to use for when the spinner is complete.

• custom_icons: A list of strings to use as the spinner icon. Overrides icons_id

• interval: The delay between spinner icon updates.

• position: Where the spinner should be placed on a line.

• indent: How many spaces the line should be indented.

• spinner_color: Color of the spinner icon while active. [1]

• done_color: Color for the spinner icon when stopped. [1]

Spinner.BUILTIN_ICONS contains all the spinner animations built into the library. It’s formatted as <id>: <frames>, with the id being used for the icons_id parameter. Each string in the list is one frame of the spinner animation.

The main functions of Spinner include:

• start(): The main method of starting the spinner. It optionally takes a text parameter.

• stop(): Will preform the following actions:

  1. Stops the current spinner

  2. Removes or replaces the spinner on the line

     1. If a done_icon was provided OR one was set earlier, it will replace the spinner.

     2. If none was provided OR done_icon wasn’t set earlier, the spinner will be removed.

Warning

Spinner.start() will hide the cursor until Spinner.stop() is called. To prevent cases where the cursor remains invisible after force exiting the program, include Spinner.stop() in your try-except block as shown in the examples below.

• update(): Allows changing values of the spinner.

Note

The following are the only values that can be changed while the spinner is running:

• done_icon

• done_color

• text

Examples

A very simple spinner looks something like this:

from time import sleep
sp: Spinner = Spinner()
try:
    sp.start()
    sleep(10)  # Some task here
    sp.stop()
except (EOFError, KeyboardInterrupt):
    sp.stop()

Colors

Most classes in framed_text have parameters for termcolor colors.

The value can be either a termcolor color code or an (R, G, B) tuple, where each value is between 0 and 255.

For a full list of termcolor color codes, see termcolor’s Text Properties.

Attributes

Attention

Not all of termcolor’s attributes are supported by every terminal emulator or operating system.

Your milage may vary

Most classes in framed_text have parameters for termcolor attributes.

All termcolor attributes are supported. Below is a list of all valid attributes currently available:

• bold

• dark

• italic

• underline

• blink

• reverse

• concealed

• strike

Showcase of all attributes using FramedText and LabeledData.String

---

Notes

[1] (1,2,3,4,5,6,7)

See Colors for more information.

[2] (1,2,3,4)

See Attributes for more information.

[3] (1,2)

Uses a custom method of shortening text, typically found in their source class. These will not use ShortenText. See their respective sections for more information.

[4] (1,2)

Overrides unit_match value