Version: Next

Tutorial

Introduction#

In this hands-on tutorial, we will take a look at how we can use Yew to build web applications. Yew is a modern Rust framework for building front-end web apps using WebAssembly. Yew encourages a reusable, maintainable, and well-structured architecture by leveraging Rust's powerful type system. A large ecosystem of community-created libraries, known in Rust as crates, provide components for commonly-used patterns such as state management. Cargo, the package manager for Rust, allows us to take advantage of the numerous crates available on crates.io, such as Yew.

What we are going to build#

Rustconf is an intergalactic gathering of the Rust community that happens annually. Rustconf 2020 had a plethora of talks that provided a good amount of information. In this hands-on tutorial, we will be building a web application to help fellow Rustaceans get an overview of the talks and watch them all from one page.

Setting up#

Prerequisites#

This tutorial assumes you are already familiar with Rust. If you are new to Rust, the free Rust Book offers a great starting point for beginners and continues to be an excellent resource even for experienced Rust developers.

Ensure the latest version of Rust is installed by running rustup update or by installing rust if you have not already done so.

After installing Rust, you can use Cargo to install trunk by running:

cargo install trunk

We will also need to add the WASM build target by running:

rustup target add wasm32-unknown-unknown

Setting up the project#

First, create a new cargo project:

cargo new yew-app
cd yew-app

To verify the Rust environment is set up properly, run the initial project using the cargo build tool. After the output about the build process, you should see the expected "Hello, world!" message.

cargo run

Our first static page#

To convert this simple command line application to a basic Yew web application, a few changes are needed. Update the files as follows:

Cargo.toml

[package]
name = "yew-app"
version = "0.1.0"
edition = "2021"

[dependencies]
yew = { git = "https://github.com/yewstack/yew/", features = ["csr"] }

info

You only need the feature csr if you are building an application. It will enable the Renderer and all client-side rendering-related code.

If you are making a library, do not enable this feature as it will pull in client-side rendering logic into the server-side rendering bundle.

If you need the Renderer for testing or examples, you should enable it in the dev-dependencies instead.

src/main.rs

use yew::prelude::*;

#[component]
fn App() -> Html {
    html! {
        <h1>{ "Hello World" }</h1>
    }
}

fn main() {
    yew::Renderer::<App>::new().render();
}

Now, let's create an index.html at the root of the project.

index.html

<!doctype html>
<html lang="en">
    <head></head>
    <body></body>
</html>

Start the development server#

Run the following command to build and serve the application locally.

trunk serve --open

info

Remove option '--open' to not open your default browser trunk serve.

Trunk will open your application in your default browser, watch the project directory and helpfully rebuild your application if you modify any source files. This will fail if the socket is being used by another application. By default server will be listening at address '127.0.0.1' and port '8080' => http://localhost:8080. To change it, create the following file and edit as needed:

Trunk.toml

[serve]
# The address to serve on LAN.
address = "127.0.0.1"
# The address to serve on WAN.
# address = "0.0.0.0"
# The port to serve on.
port = 8000

If you are curious, you can run trunk help and trunk help <subcommand> for more details on what is happening.

Congratulations#

You have now successfully set up your Yew development environment and built your first Yew web application.

Building HTML#

Yew makes use of Rust's procedural macros and provides us with a syntax similar to JSX (an extension to JavaScript which allows you to write HTML-like code inside JavaScript) to create the markup.

Converting classic HTML#

Since we already have a pretty good idea of what our website will look like, we can simply translate our mental draft into a representation compatible with html!. If you are comfortable writing simple HTML, you should have no problem writing marking inside html!. It is important to note that the macro does differ from HTML in a few ways:

Expressions must be wrapped in curly braces ({ })
There must only be one root node. If you want to have multiple elements without wrapping them in a container, an empty tag/fragment (<> ... </>) is used
Elements must be closed properly.

We want to build a layout that looks something like this in raw HTML:

<h1>RustConf Explorer</h1>
<div>
    <h3>Videos to watch</h3>
    <p>John Doe: Building and breaking things</p>
    <p>Jane Smith: The development process</p>
    <p>Matt Miller: The Web 7.0</p>
    <p>Tom Jerry: Mouseless development</p>
</div>
<div>
    <h3>John Doe: Building and breaking things</h3>
    <img
        src="https://placehold.co/640x360.png?text=Video+Player+Placeholder"
        alt="video thumbnail"
    />
</div>

Now, let's convert this HTML into html!. Type (or copy/paste) the following snippet into the body of app function such that the value of html! is returned by the function

#[component]
fn App() -> Html {
    html! {
        <>
            <h1>{ "RustConf Explorer" }</h1>
            <div>
                <h3>{ "Videos to watch" }</h3>
                <p>{ "John Doe: Building and breaking things" }</p>
                <p>{ "Jane Smith: The development process" }</p>
                <p>{ "Matt Miller: The Web 7.0" }</p>
                <p>{ "Tom Jerry: Mouseless development" }</p>
            </div>
            <div>
                <h3>{ "John Doe: Building and breaking things" }</h3>
                <img src="https://placehold.co/640x360.png?text=Video+Player+Placeholder" alt="video thumbnail" />
            </div>
        </>
    }
}

Refresh the browser page, and you should see the following output displayed:

Using Rust language constructs in the markup#

A big advantage of writing markup in Rust is that we get all the coolness of Rust in our markup. Now, instead of hardcoding the list of videos in the HTML, let's define them as a Vec of Video structs. We create a simple struct (in main.rs or any file of our choice) that will hold our data.

#[derive(Clone, PartialEq)]
struct Video {
    id: usize,
    title: AttrValue,
    speaker: AttrValue,
    url: AttrValue,
}

Next, we will create instances of this struct in our app function and use those instead of hardcoding the data:

#[component]
fn App() -> Html {
    let videos = vec![
        Video {
            id: 1,
            title: "Building and breaking things".into(),
            speaker: "John Doe".into(),
            url: "https://youtu.be/PsaFVLr8t4E".into(),
        },
        Video {
            id: 2,
            title: "The development process".into(),
            speaker: "Jane Smith".into(),
            url: "https://youtu.be/PsaFVLr8t4E".into(),
        },
        Video {
            id: 3,
            title: "The Web 7.0".into(),
            speaker: "Matt Miller".into(),
            url: "https://youtu.be/PsaFVLr8t4E".into(),
        },
        Video {
            id: 4,
            title: "Mouseless development".into(),
            speaker: "Tom Jerry".into(),
            url: "https://youtu.be/PsaFVLr8t4E".into(),
        },
    ];

To display them, we can use a for loop right in the macro in place of the hardcoded HTML:

    html! {
        <>
            <h1>{ "RustConf Explorer" }</h1>
            <div>
                <h3>{ "Videos to watch" }</h3>
                for video in &videos {
                    <p key={video.id}>{format!("{}: {}", video.speaker, video.title)}</p>
                }
            </div>
            // ...
        </>
    }

tip

Keys on list items help Yew keep track of which items have changed in the list, resulting in faster re-renders. It is always recommended to use keys in lists.

Components#

Components are the building blocks of Yew applications. By combining components, which can be made of other components, we build our application. By structuring our components for re-usability and keeping them generic, we will be able to use them in multiple parts of our application without having to duplicate code or logic.

The app function we have been using so far is a component, called App. It is a "function component". There are two different types of components in Yew.

Struct Components
Function Components

In this tutorial, we will be using function components.

Now, let's split up our App component into smaller components. We begin by extracting the videos list into its own component.

#[derive(Properties, PartialEq)]
struct VideosListProps {
    videos: Vec<Video>,
}

#[component]
fn VideosList(VideosListProps { videos }: &VideosListProps) -> Html {
    html! {
        for video in videos {
            <p key={video.id}>{format!("{}: {}", video.speaker, video.title)}</p>
        }
    }
}

Notice the parameters of our VideosList function component. A function component takes only one argument which defines its "props" (short for "properties"). Props are used to pass data down from a parent component to a child component. In this case, VideosListProps is a struct that defines the props.

important

The struct used for props must implement Properties by deriving it.

Now, we can update our App component to make use of VideosList component.

#[component]
fn App() -> Html {
    // ...
    html! {
        <>
            <h1>{ "RustConf Explorer" }</h1>
            <div>
                <h3>{ "Videos to watch" }</h3>
                <VideosList {videos} />
            </div>
            // ...
        </>
    }
}

By looking at the browser window, we can verify that the lists are rendered as they should be. We have moved the rendering logic of lists to its component. This shortens the App component's source code, making it easier for us to read and understand.

Making it interactive#

The final goal here is to display the selected video. To do that, VideosList component needs to "notify" its parent when a video is selected, which is done via a Callback. This concept is called "passing handlers". We modify its props to take an on_click callback:

#[derive(Properties, PartialEq)]
struct VideosListProps {
    videos: Vec<Video>,
    on_click: Callback<Video>,
}

Then we modify the VideosList component to "emit" the selected video to the callback.

#[component]
-fn VideosList(VideosListProps { videos }: &VideosListProps) -> Html {
+fn VideosList(VideosListProps { videos, on_click }: &VideosListProps) -> Html {
    let on_select = |video: &Video| {
        let on_click = on_click.clone();
        let video = video.clone();
        Callback::from(move |_| {
            on_click.emit(video.clone())
        })
    };
 
    html! {
        for video in videos {
            <p key={video.id} onclick={on_select(video)}>{format!("{}: {}", video.speaker, video.title)}</p>
        }
    }
}

Next, we need to modify the usage of VideosList to pass that callback. But before doing that, we should create a new component, VideoDetails, that is displayed when a video is clicked.

#[derive(Properties, PartialEq)]
struct VideosDetailsProps {
    video: Video,
}

#[component]
fn VideoDetails(VideosDetailsProps { video }: &VideosDetailsProps) -> Html {
    html! {
        <div>
            <h3>{ &*video.title }</h3>
            <img src="https://placehold.co/640x360.png?text=Video+Player+Placeholder" alt="video thumbnail" />
        </div>
    }
}

Now, modify the App component to display VideoDetails component whenever a video is selected.

        },
    ];
 
    let selected_video = use_state(|| None);
 
    let on_video_select = {
        let selected_video = selected_video.clone();
        Callback::from(move |video: Video| {
            selected_video.set(Some(video))
        })
    };

    html! {
        <>
            <h1>{ "RustConf Explorer" }</h1>
            <div>
                <h3>{ "Videos to watch" }</h3>
                <VideosList {videos} on_click={on_video_select} />
            </div>
            if let Some(video) = &*selected_video {
                <VideoDetails video={video.clone()} />
            }
        </>
    }

Handling state#

Remember the use_state used earlier? That is a special function, called a "hook". Hooks are used to "hook" into the lifecycle of a function component and perform actions. You can learn more about this hook, and others here.

note

Struct components act differently. See the documentation to learn about those.

Fetching data (using external REST API)#

In a real-world application, data will usually come from an API instead of being hardcoded. Let's fetch our videos list from an external source. For this we will need to add the following crates:

gloo-net - For making the fetch call.
serde with derive features - For de-serializing the JSON response
wasm-bindgen-futures - For executing Rust Future as a Promise

Let's update the dependencies in Cargo.toml file:

Cargo.toml

[dependencies]
yew = { git = "https://github.com/yewstack/yew/", features = ["csr", "serde"] }
gloo-net = "0.6"
serde = { version = "1.0", features = ["derive"] }
wasm-bindgen-futures = "0.4"

Yew's serde feature enables integration with the serde crate, the important point for us is that it adds a serde::Deserialize impl to AttrValue.

note

When choosing dependencies make sure they are wasm32 compatible! Otherwise you won't be able to run your application.

Update the Video struct to derive the Deserialize trait:

use yew::prelude::*;
+use serde::Deserialize;
// ...
-#[derive(Clone, PartialEq)]
+#[derive(Clone, PartialEq, Deserialize)]
struct Video {
    id: usize,
    title: AttrValue,
    speaker: AttrValue,
    url: AttrValue,
}

Now as the last step, we need to update our App component to make the fetch request instead of using hardcoded data

use yew::prelude::*;
+use gloo_net::http::Request;

#[component]
fn App() -> Html {
    let videos = use_state(|| vec![]);
    {
        let videos = videos.clone();
        use_effect_with((), move |_| {
            let videos = videos.clone();
            wasm_bindgen_futures::spawn_local(async move {
                let fetched_videos: Vec<Video> = Request::get("https://yew.rs/tutorial/data.json")
                    .send()
                    .await
                    .unwrap()
                    .json()
                    .await
                    .unwrap();
                videos.set(fetched_videos);
            });
            || ()
        });
    }

    // ...

    html! {
        <>
            <h1>{ "RustConf Explorer" }</h1>
            <div>
                <h3>{ "Videos to watch" }</h3>
                <VideosList videos={(*videos).clone()} on_click={on_video_select} />
            </div>
            // ...
        </>
    }
}

note

We are using unwraps here because this is a demo application. In a real-world app, you would likely want to have proper error handling.

Now, look at the browser to see everything working as expected... which would have been the case if it were not for CORS. To fix that, we need a proxy server. Luckily trunk provides that.

Update the following line:

                let fetched_videos: Vec<Video> = Request::get("/tutorial/data.json")

Now, rerun the server with the following command:

trunk serve --proxy-backend=https://yew.rs/tutorial

Refresh the tab and everything should work as expected.

Wrapping up#

Congratulations! You've created a web application that fetches data from an external API and displays a list of videos.

What's next#

This application is very far from perfect or useful. After going through this tutorial, you can use it as a jumping-off point to explore more advanced topics.

Styles#

Our apps look very ugly. There is no CSS or any kind of style. Unfortunately, Yew does not offer a built-in way to style components. See Trunk's assets to learn how to add style sheets.

More libraries#

Our app made use of only a few external dependencies. There are lots of crates out there that can be used. See external libraries for more details.

Learning more about Yew#

Read our official documentation. It explains a lot of concepts in much more detail. To learn more about the Yew API, see our API docs.

Edit this page