Raxol.Components.Progress (Raxol v0.2.0)

View Source

Provides components for displaying progress, like progress bars and spinners.

Summary

Functions

Renders a simple progress bar with configurable appearance.

Renders a progress bar with a label and optional percentage display.

Renders a circular progress indicator.

Renders an indeterminate progress bar (animated).

Renders a spinner animation for indicating loading or processing.

Returns the available spinner types.

Functions

bar(value, opts \\ [])

Renders a simple progress bar with configurable appearance.

Parameters

  • value - Current progress value (0.0 to 1.0)
  • opts - Options for customizing the progress bar

Options

  • :id - Unique identifier for the progress bar (default: "progress_bar")
  • :width - Width of the progress bar in characters (default: 20)
  • :style - Style for the progress bar container
  • :filled_style - Style for the filled portion of the bar (default: %{bg: :blue})
  • :empty_style - Style for the empty portion of the bar (default: %{bg: :black})
  • :chars - Characters to use for different parts of the bar
    • :filled - Character for filled sections (default: " ")
    • :empty - Character for empty sections (default: " ")

Returns

A view element representing the progress bar.

Example

Progress.bar(
  0.75,
  width: 30,
  filled_style: %{bg: :green},
  chars: %{filled: "█", empty: "░"}
)

bar_with_label(value, label, opts \\ [])

Renders a progress bar with a label and optional percentage display.

Parameters

  • value - Current progress value (0.0 to 1.0)
  • label - Text label to display
  • opts - Options for customizing the progress bar

Options

All options from bar/2 plus:

  • :show_percentage - Whether to show percentage (default: true)
  • :percentage_style - Style for the percentage text (default: %{})
  • :label_style - Style for the label text (default: %{})
  • :position - Position of the label/percentage (:above, :below, :right, default: :above)

Returns

A view element representing the progress bar with label.

Example

Progress.bar_with_label(
  0.35,
  "Loading assets...",
  show_percentage: true,
  position: :below,
  filled_style: %{bg: :cyan}
)

broadcast(msg)

circular(value, opts \\ [])

Renders a circular progress indicator.

Parameters

  • value - Current progress value (0.0 to 1.0)
  • opts - Options for customizing the progress indicator

Options

  • :id - Unique identifier for the indicator (default: "circular_progress")
  • :style - Style for the indicator
  • :show_percentage - Whether to show percentage inside (default: true)
  • :percentage_style - Style for the percentage text

Returns

A view element representing the circular progress indicator.

Example

Progress.circular(
  0.65,
  style: %{fg: :green}
)

command(cmd)

indeterminate(frame, opts \\ [])

Renders an indeterminate progress bar (animated).

Parameters

  • frame - Current animation frame (integer, typically incremented on each render)
  • opts - Options for customizing the indeterminate progress bar

Options

  • :id - Unique identifier for the progress bar (default: "indeterminate_progress")
  • :width - Width of the progress bar in characters (default: 20)
  • :style - Style for the progress bar container
  • :bar_style - Style for the animated bar (default: %{bg: :blue})
  • :background_style - Style for the background (default: %{bg: :black})
  • :segment_size - Size of the animated segment (default: 5)

Returns

A view element representing the indeterminate progress bar.

Example

Progress.indeterminate(
  model.animation_frame,
  width: 30,
  bar_style: %{bg: :purple},
  segment_size: 8
)

mount(state)

Callback implementation for Raxol.UI.Components.Base.Component.mount/1.

schedule(msg, delay)

spinner(message \\ nil, frame, opts \\ [])

Renders a spinner animation for indicating loading or processing.

Parameters

  • message - Optional message to display next to the spinner
  • frame - Current animation frame (integer, typically incremented on each render)
  • opts - Options for customizing the spinner

Options

  • :id - Unique identifier for the spinner (default: "spinner")
  • :style - Style for the spinner container
  • :spinner_style - Style for the spinner character
  • :message_style - Style for the message text
  • :type - Type of spinner animation (default: :dots)

Returns

A view element representing the spinner.

Example

# In your update function, increment the frame on each update
def update(model, :tick) do
  %{model | spinner_frame: model.spinner_frame + 1}
end

# In your view function
Progress.spinner(
  "Processing data...",
  model.spinner_frame,
  type: :braille,
  spinner_style: %{fg: :cyan}
)

spinner_types()

Returns the available spinner types.

Returns

A map of spinner types to their frame sequences.

Example

spinner_types = Progress.spinner_types()

unmount(state)

Callback implementation for Raxol.UI.Components.Base.Component.unmount/1.