Guide · Open source
How to use iced: Rust GUI tutorial with a counter example
Updated · written with AI from the project's own documentation and checked against our catalogue data
Iced is an open-source cross-platform GUI library for Rust, focused on simplicity and type safety and inspired by Elm. It is aimed at Rust developers who want to build windowed graphical interfaces as a library inside their own program. After this guide you will understand the four parts of an Iced app (state, messages, view and update) and how they fit together in a small counter example.
Icediced-rs/iced · ★ 31.9k · MIT Install options & downloads Quick start
- 1Install a Rust toolchain. Make sure Rust is installed, since iced is a Rust crate. The README does not state a minimum version.
- 2Clone the repository. Run git clone https://github.com/iced-rs/iced to get the source, examples and links to the book.
- 3Model your state. Create a struct that holds your application data, such as a counter value.
- 4Define your messages. Create an enum with one variant per user interaction you want to handle.
- 5Write the view. Return widgets from a view function and attach a message to each interactive widget with on_press.
- 6Write the update. Match on each message and change the state accordingly.
- 7Run the app. Call iced::run with your update and view functions from main.
What you need before you start with iced
Iced is a Rust crate, so you need a Rust toolchain installed. The README excerpt does not state a specific Rust version, so check the project's documentation for the version it requires.
Iced is a library you build your own program with, not an application you install and run. The README says it targets Windows, macOS, Linux, and the Web.
- A working Rust toolchain
- Basic familiarity with Rust enums, structs and match expressions
- Optional: a clone of the repository to browse the examples
Get the iced source code
The README's install instruction is to clone the repository. Clone it to a local folder so you can read the book, the documentation and the examples that the project links to.
- Clone the repository to your machine
- Browse the examples folder for runnable programs
git clone https://github.com/iced-rs/icedUnderstand the four parts of an iced app
Iced follows The Elm Architecture and splits a user interface into four concepts. State holds your application's data. Messages represent user interactions or meaningful events. View logic displays the state as widgets that can produce messages. Update logic reacts to messages and changes the state.
Iced then does three things for you: it lays out the widgets returned by your view, it turns system events into messages for your update logic, and it draws the resulting interface.
- State: the data of your application
- Messages: user interactions or events you care about
- View: displays state as widgets that may produce messages
- Update: reacts to messages and modifies state
Build a counter: state, messages and view
The README's example is a counter that increments and decrements with two buttons. First, model the state as a struct with a default value.
Next, define the messages for the two button presses. Then write a view function that places two buttons and a text label in a column. Each button is given a message to produce when pressed.
#[derive(Default)]
struct Counter {
value: i32,
}
#[derive(Debug, Clone, Copy)]
pub enum Message {
Increment,
Decrement,
}
use iced::widget::{button, column, text, Widget};
impl Counter {
pub fn view(&self) -> impl Widget<Message> {
column![
button("+").on_press(Message::Increment),
text(self.value).size(50),
button("-").on_press(Message::Decrement),
]
}
}Add the update logic and run the app
The update function receives a message and changes the state to match. Increment adds one to the value and Decrement subtracts one.
To start the program, call the run function with your update and view functions. The README shows this as the entry point of the example.
impl Counter {
pub fn update(&mut self, message: Message) {
match message {
Message::Increment => {
self.value += 1;
}
Message::Decrement => {
self.value -= 1;
}
}
}
}
fn main() -> iced::Result {
iced::run(Counter::update, Counter::view)
}Where to learn more about iced
The README points to three resources for further learning: the book, the documentation and the examples. It also links to a roadmap and the issue tracker, and to Zulip and Discord for questions and feedback.
- Book: book.iced.rs
- Documentation: docs.rs/iced
- Examples: the examples folder in the repository
- Roadmap and open issues on GitHub
What people use it for
- Building a desktop GUI for a Rust tool that needs buttons, text inputs and scrollable lists
- Creating a custom widget for a specialised interface
- Plugging the renderer-agnostic runtime into an existing system
- Prototyping a small interactive program in pure Rust
Frequently asked questions
Is iced free to use?
Iced is released under the MIT licence, as shown in the project's metadata. Check the LICENSE file in the repository for the full terms.
Is iced production ready?
No. The README states that Iced is currently experimental software, so teams that need a production-stable UI toolkit should consider other options.
Which platforms does iced support?
The README says it targets Windows, macOS, Linux, and the Web. Two built-in renderers are listed: iced_wgpu for Vulkan, Metal and DX12, and iced_tiny_skia as a software fallback.
Do I need to know Rust to use iced?
Yes. Iced is a Rust library, so you write your app in Rust. It is not meant for people who do not program in Rust.
How does iced compare to egui, Slint, Tauri and Druid?
These are comparable projects, as listed in our analysis. Iced's distinguishing features in the README are its Elm-style architecture and its renderer-agnostic runtime. For a direct comparison of trade-offs, read each project's own documentation.
Can I write custom widgets in iced?
Yes. The README lists custom widget support as a feature and says you can create your own.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Iced suits Rust developers who want to build a desktop or web GUI with an Elm-style state, message and update pattern, and who are comfortable with an experimental library. If you do not write Rust, need a stable production toolkit, or want an end-user app to install, pick a different tool.
Install options & downloads