ProgressBar for Elixir

Do you have a use case not listed below? Please open an issue or pull request!

Usage

Specify the current value and the total value, and a bar will be rendered to STDOUT.

ProgressBar.render(2, 3)

Output:

[===================================================================                                 |  67%

Call the function again and it will overwrite the previous bar with the new value:

ProgressBar.render(2, 3)
ProgressBar.render(3, 3)

Output:

[====================================================================================================| 100%

This basically works by printing "\r[===…" each time, without a newline. The text cursor will return to the beginning of the line and overwrite the previous value.

When the bar becomes full, a newline is automatically printed, so any subsequent output gets its own line.

It's up to you to re-render the bar when something changes. Here's a trivial example of an animated progress bar:

Enum.each 1, 100, fn (i) ->
  ProgressBar.render(i, 100)
  :timer.sleep 25
end

To see it in action, clone this repo and run the example scripts:

# See what's available.
ls examples

# Run an example.
mix run examples/default.exs

Customize format

Replace the bar, blank, left or right characters.

format = [
  bar: "X",   # default: "="
  blank: ".", # default: " "
  left: "(",  # default: "|"
  right: ")", # default: "|"
]

ProgressBar.render(97, 100, format)

Output:

…XXXXXXXXX...)  97%

You can provide empty-string values to remove left and right entirely.

Customize color

Specify IO.ANSI values as bar_color or blank_color. Use lists for multiple values.

format = [
  bar_color: [IO.ANSI.white, IO.ANSI.green_background],
  blank_color: IO.ANSI.red_background,
]

ProgressBar.render(97, 100, format)

percent: false

Hides the percent shown after the bar.

ProgressBar.render(1, 1, percent: false)

Output:

…============|

bytes: true

This option causes the values to be treated as bytes of data, showing those amounts next to the bar.

ProgressBar.render(2_034_237, 2_097_152, bytes: true)

Output:

…=========   |  97% (1.94/2.0 MB)

Installation

Add the dependency to your project's mix.exs:

defp deps do
  [
    {:progress_bar, "> 0.0.0"},
  ]
end

Then fetch it:

mix deps.get

Tests

mix test

Credits and license

By Henrik Nyh 2015-09-19 under the MIT license.