Events
Introduction
Yew integrates with the web-sys
crate and
uses the events from that crate. The table below lists all of the web-sys
events that are accepted in the html!
macro.
You can still add a Callback
for an event that is not listed in the table
below, see Manual event listener.
Event Types
All the event types mentioned in the following table are re-exported under yew::events
.
Using the types from yew::events
makes it easier to ensure version compatibility than
if you were to manually include web-sys
as a dependency in your crate because you will not
end up using a version which conflicts with the version that Yew specifies.
The event listener name is the expected name when adding an event Callback
in the html
macro:
use yew::prelude::*;
html! {
<button onclick={Callback::from(|_| ())}>
// ^^^^^^^ event listener name
{ "Click me!" }
</button>
};
The event name is the listener without the "on" prefix, therefore, the onclick
event listener
listens for click
events. See the end of this page for a full list of available event with their types.
Event bubbling
Events dispatched by Yew follow the virtual DOM hierarchy when bubbling up to listeners. Currently, only the bubbling phase
is supported for listeners. Note that the virtual DOM hierarchy is most often, but not always, identical to the actual
DOM hierarchy. The distinction is important when working with portals and other
more advanced techniques. The intuition for well-implemented components should be that events bubble from children
to parents. In this way the hierarchy in your coded html!
is the one observed by event handlers.
If you are not interested in event bubbling, you can turn it off by calling
yew::set_event_bubbling(false);
before starting your app. This speeds up event handling, but some components may break from not receiving the events they expect. Use this with care!
Event delegation
It can be surprising that event listeners are not directly registered on the element where they are rendered. Instead, events are delegated from the subtree root of the Yew app. Still, events are delivered in their native form, and no synthetic form is created. This can lead to mismatches between the event you would expect in HTML listeners and those showing up in Yew.
-
Event::current_target
points to the Yew subtree root instead of the element the listener is added on. UseNodeRef
if you want access to the underlyingHtmlElement
. -
Event::event_phase
is alwaysEvent::CAPTURING_PHASE
. Internally, the event will behave as if it was in the bubbling phase, the event propagation is replayed and the event bubbles up, i.e. event listeners higher up in the virtual DOM will trigger after event listeners below them. Currently, capturing listeners is not supported by Yew.This also means that events registered by Yew will usually fire before other event listeners.
Typed event target
In this section target (Event.target
)
is always referring to the element at which the event was dispatched from.
This will not always be the element at which the Callback
is placed.
In event Callback
s you may want to get the target of that event. For example, the
change
event gives no information but is used to notify that something has changed.
In Yew getting the target element in the correct type can be done in a few ways and we will go through
them here. Calling web_sys::Event::target
on an event returns an optional web_sys::EventTarget
type, which might not seem very useful when you want to know the value of your input element.
In all the approaches below we are going to tackle the same problem, so it is clear where the approach differs as opposed to the problem at hand.
The Problem:
We have an onchange
Callback
on my <input>
element and each time it is invoked we want to send
an update Msg
to our component.
Our Msg
enum looks like this:
pub enum Msg {
InputValue(String),
}