Struct Program 

pub struct Program<M: Model> { /* private fields */ }

The main program runner.

Program manages the entire lifecycle of a TUI application:

• Terminal setup and teardown
• Event polling and message dispatching
• Frame-rate limited rendering

Example

use bubbletea::Program;

let model = MyModel::new();
let final_model = Program::new(model)
    .with_alt_screen()
    .run()?;

Implementations

impl<M: Model> Program<M>

pub fn new(model: M) -> Self

Create a new program with the given model.

pub fn with_input_receiver(self, rx: Receiver<Message>) -> Self

Provide an external message receiver.

Messages received on this channel will be forwarded to the program’s event loop. This is useful for injecting events from external sources (e.g. SSH).

pub fn with_input<R: Read + Send + 'static>(self, input: R) -> Self

Provide a custom input reader.

This enables custom I/O mode and reads raw bytes from the given reader, translating them into Bubbletea messages.

pub fn with_output<W: Write + Send + 'static>(self, output: W) -> Self

Provide a custom output writer.

This enables custom I/O mode and writes render output to the given writer.

pub fn with_alt_screen(self) -> Self

Use alternate screen buffer (full-screen mode).

pub fn with_mouse_cell_motion(self) -> Self

Enable mouse cell motion tracking.

Reports mouse clicks and drags.

pub fn with_mouse_all_motion(self) -> Self

Enable mouse all motion tracking.

Reports all mouse movement, even without button presses.

pub fn with_fps(self, fps: u32) -> Self

Set the target frames per second.

Default is 60 FPS. Valid range is 1-120 FPS.

pub fn with_report_focus(self) -> Self

Enable focus reporting.

Sends FocusMsg and BlurMsg when terminal gains/loses focus.

pub fn without_bracketed_paste(self) -> Self

Disable bracketed paste mode.

pub fn without_signal_handler(self) -> Self

Disable signal handling.

pub fn without_catch_panics(self) -> Self

Don’t catch panics.

pub fn with_custom_io(self) -> Self

Enable custom I/O mode (skip terminal setup and crossterm polling).

This is useful when embedding bubbletea in environments that manage terminal state externally or when events are injected manually.

pub fn run_with_writer<W: Write + Send + 'static>(self, writer: W) -> Result<M>

Run the program with a custom writer.

pub fn run(self) -> Result<M>

Run the program and return the final model state.

pub fn start(self) -> ProgramHandle<M>

Start the program in a background thread and return a handle for interaction.

This is useful for SSH applications and other scenarios where you need to inject events from external sources after the program has started.

Example

use bubbletea::{Program, Message};

let handle = Program::new(MyModel::default())
    .with_custom_io()
    .start();

// Inject a key event
handle.send(KeyMsg::from_char('a'));

// Later, quit the program
handle.quit();

// Wait for completion
let final_model = handle.wait()?;