yew/
lib.rs

1#![allow(clippy::needless_doctest_main)]
2#![doc(html_logo_url = "https://yew.rs/img/logo.png")]
3#![cfg_attr(documenting, feature(doc_cfg))]
4#![cfg_attr(documenting, feature(doc_auto_cfg))]
5#![cfg_attr(nightly_yew, feature(fn_traits, unboxed_closures))]
6
7//! # Yew Framework - API Documentation
8//!
9//! Yew is a modern Rust framework for creating multi-threaded front-end web apps using WebAssembly
10//!
11//! - Features a macro for declaring interactive HTML with Rust expressions. Developers who have
12//!   experience using JSX in React should feel quite at home when using Yew.
13//! - Achieves high performance by minimizing DOM API calls for each page render and by making it
14//!   easy to offload processing to background web workers.
15//! - Supports JavaScript interoperability, allowing developers to leverage NPM packages and
16//!   integrate with existing JavaScript applications.
17//!
18//! ### Supported Targets (Client-Side Rendering)
19//! - `wasm32-unknown-unknown`
20//!
21//! ### Note
22//!
23//! Server-Side Rendering should work on all targets when feature `ssr` is enabled.
24//!
25//! ### Supported Features:
26//! - `csr`: Enables Client-side Rendering support and [`Renderer`]. Only enable this feature if you
27//!   are making a Yew application (not a library).
28//! - `ssr`: Enables Server-side Rendering support and [`ServerRenderer`].
29//! - `hydration`: Enables Hydration support.
30//!
31//! ## Example
32//!
33//! ```rust,no_run
34//! use yew::prelude::*;
35//!
36//! enum Msg {
37//!     AddOne,
38//! }
39//!
40//! struct App {
41//!     value: i64,
42//! }
43//!
44//! impl Component for App {
45//!     type Message = Msg;
46//!     type Properties = ();
47//!
48//!     fn create(ctx: &Context<Self>) -> Self {
49//!         Self { value: 0 }
50//!     }
51//!
52//!     fn update(&mut self, _ctx: &Context<Self>, msg: Self::Message) -> bool {
53//!         match msg {
54//!             Msg::AddOne => {
55//!                 self.value += 1;
56//!                 true
57//!             }
58//!         }
59//!     }
60//!
61//!     fn view(&self, ctx: &Context<Self>) -> Html {
62//!         html! {
63//!             <div>
64//!                 <button onclick={ctx.link().callback(|_| Msg::AddOne)}>{ "+1" }</button>
65//!                 <p>{ self.value }</p>
66//!             </div>
67//!         }
68//!     }
69//! }
70//!
71//! fn main() {
72//!     yew::Renderer::<App>::new().render();
73//! }
74//! ```
75
76#![deny(
77    missing_docs,
78    missing_debug_implementations,
79    bare_trait_objects,
80    anonymous_parameters,
81    elided_lifetimes_in_paths
82)]
83#![allow(macro_expanded_macro_exports_accessed_by_absolute_paths)]
84#![recursion_limit = "512"]
85extern crate self as yew;
86
87/// This macro provides a convenient way to create [`Classes`].
88///
89/// The macro takes a list of items similar to the [`vec!`] macro and returns a [`Classes`]
90/// instance. Each item can be of any type that implements `Into<Classes>` (See the
91/// implementations on [`Classes`] to learn what types can be used).
92///
93/// # Example
94///
95/// ```
96/// # use yew::prelude::*;
97/// # fn test() {
98/// let conditional_class = Some("my-other-class");
99/// let vec_of_classes = vec![
100///     "one-bean",
101///     "two-beans",
102///     "three-beans",
103///     "a-very-small-casserole",
104/// ];
105///
106/// html! {
107///     <div class={classes!("my-container-class", conditional_class, vec_of_classes)}>
108///         // ...
109///     </div>
110/// };
111/// # }
112/// ```
113pub use yew_macro::classes;
114/// This macro implements JSX-like templates.
115///
116/// This macro always returns [`Html`].
117/// If you need to preserve the type of a component, use the [`html_nested!`] macro instead.
118///
119/// More information about using the `html!` macro can be found in the [Yew Docs]
120///
121/// [`Html`]: ./html/type.Html.html
122/// [`html_nested!`]: ./macro.html_nested.html
123/// [Yew Docs]: https://yew.rs/docs/next/concepts/html
124pub use yew_macro::html;
125/// This macro is similar to [`html!`], but preserves the component type instead
126/// of wrapping it in [`Html`].
127///
128/// That macro is useful when, for example, in a typical implementation of a list
129/// component (let's assume it's called `List`).
130/// In a typical implementation you might find two component types -- `List` and `ListItem`.
131/// Only `ListItem` components are allowed to be children of List`.
132///
133/// You can find an example implementation of this in the [`nested_list`] example.
134/// That example shows, how to create static lists with their children.
135///
136/// ```
137/// # use yew::prelude::*;
138/// use yew::html::ChildrenRenderer;
139/// use yew::virtual_dom::VChild;
140///
141/// #[derive(Clone, Properties, PartialEq)]
142/// struct ListProps {
143///     children: ChildrenRenderer<ListItem>,
144/// }
145///
146/// struct List;
147/// impl Component for List {
148/// #   type Message = ();
149///     type Properties = ListProps;
150///     // ...
151/// #   fn create(ctx: &Context<Self>) -> Self { Self }
152/// #   fn view(&self, ctx: &Context<Self>) -> Html { unimplemented!() }
153/// }
154///
155/// #[derive(Clone, PartialEq)]
156/// struct ListItem;
157/// impl Component for ListItem {
158/// #   type Message = ();
159/// #   type Properties = ();
160///     // ...
161/// #   fn create(ctx: &Context<Self>) -> Self { Self }
162/// #   fn view(&self, ctx: &Context<Self>) -> Html { unimplemented!() }
163/// }
164///
165/// // Required for ChildrenRenderer
166/// impl From<VChild<ListItem>> for ListItem {
167///     fn from(child: VChild<ListItem>) -> Self {
168///         Self
169///     }
170/// }
171///
172/// impl Into<Html> for ListItem {
173///     fn into(self) -> Html {
174///         html! { <self /> }
175///     }
176/// }
177/// // You can use `List` with nested `ListItem` components.
178/// // Using any other kind of element would result in a compile error.
179/// # fn test() -> Html {
180/// html! {
181///   <List>
182///     <ListItem/>
183///     <ListItem/>
184///     <ListItem/>
185///   </List>
186/// }
187/// # }
188/// # fn test_iter() -> Html {
189/// # let some_iter = (0..10);
190/// // In many cases you might want to create the content dynamically.
191/// // To do this, you can use the following code:
192/// html! {
193///   <List>
194///     { for some_iter.map(|_| html_nested!{ <ListItem/> }) }
195///   </List>
196/// }
197/// # }
198/// ```
199///
200/// If you used the [`html!`] macro instead of `html_nested!`, the code would
201/// not compile because we explicitly indicated to the compiler that `List`
202/// can only contain elements of type `ListItem` using [`ChildrenRenderer<ListItem>`],
203/// while [`html!`] creates items of type [`Html`].
204///
205///
206/// [`html!`]: ./macro.html.html
207/// [`Html`]: ./html/type.Html.html
208/// [`nested_list`]: https://github.com/yewstack/yew/tree/master/examples/nested_list
209/// [`ChildrenRenderer<ListItem>`]: ./html/struct.ChildrenRenderer.html
210pub use yew_macro::html_nested;
211/// Build [`Properties`] outside of the [`html!`] macro.
212///
213/// It's already possible to create properties like normal Rust structs
214/// but if there are lots of optional props the end result is often needlessly verbose.
215/// This macro allows you to build properties the same way the [`html!`] macro does.
216///
217/// The macro doesn't support special props like `ref` and `key`, they need to be set in the
218/// [`html!`] macro.
219///
220/// You can read more about `Properties` in the [Yew Docs].
221///
222/// # Example
223///
224/// ```
225/// # use yew::prelude::*;
226/// use std::borrow::Cow;
227///
228/// #[derive(Clone, Properties, PartialEq)]
229/// struct Props {
230///     #[prop_or_default]
231///     id: usize,
232///     name: Cow<'static, str>,
233/// }
234///
235/// struct MyComponent(Props);
236/// impl Component for MyComponent {
237/// #   type Message = ();
238///     type Properties = Props;
239///     // ...
240/// #   fn create(ctx: &Context<Self>) -> Self { unimplemented!() }
241/// #   fn view(&self, ctx: &Context<Self>) -> Html { unimplemented!() }
242/// }
243///
244/// # fn foo() -> Html {
245/// // You can build props directly ...
246/// let props = yew::props!(Props {
247///     name: Cow::from("Minka")
248/// });
249/// # assert_eq!(props.name, "Minka");
250/// // ... or build the associated properties of a component
251/// let props = yew::props!(MyComponent::Properties {
252///     id: 2,
253///     name: Cow::from("Lemmy")
254/// });
255/// # assert_eq!(props.id, 2);
256///
257/// // Use the Rust-like struct update syntax to create a component with the props.
258/// html! {
259///     <MyComponent key=1 ..props />
260/// }
261/// # }
262/// ```
263///
264/// [`html!`]: ./macro.html.html
265/// [`Properties`]: ./html/trait.Properties.html
266/// [Yew Docs]: https://yew.rs/concepts/components/properties
267pub use yew_macro::props;
268
269/// This module contains macros which implements html! macro and JSX-like templates
270pub mod macros {
271    pub use crate::{classes, html, html_nested, props};
272}
273
274pub mod callback;
275pub mod context;
276#[cfg(feature = "csr")]
277mod dom_bundle;
278pub mod functional;
279pub mod html;
280pub mod platform;
281pub mod scheduler;
282mod sealed;
283#[cfg(feature = "ssr")]
284mod server_renderer;
285pub mod suspense;
286pub mod utils;
287pub mod virtual_dom;
288#[cfg(feature = "ssr")]
289pub use server_renderer::*;
290
291#[cfg(feature = "csr")]
292mod app_handle;
293#[cfg(feature = "csr")]
294mod renderer;
295
296#[cfg(all(feature = "csr", any(test, feature = "test")))]
297#[allow(missing_docs)]
298pub mod tests;
299
300/// The module that contains all events available in the framework.
301pub mod events {
302    #[doc(no_inline)]
303    pub use web_sys::{
304        AnimationEvent, DragEvent, ErrorEvent, Event, FocusEvent, InputEvent, KeyboardEvent,
305        MouseEvent, PointerEvent, ProgressEvent, SubmitEvent, TouchEvent, TransitionEvent, UiEvent,
306        WheelEvent,
307    };
308
309    #[cfg(feature = "csr")]
310    pub use crate::dom_bundle::set_event_bubbling;
311    pub use crate::html::TargetCast;
312}
313
314#[cfg(feature = "csr")]
315pub use crate::app_handle::AppHandle;
316#[cfg(feature = "csr")]
317pub use crate::renderer::{set_custom_panic_hook, Renderer};
318
319pub mod prelude {
320    //! The Yew Prelude
321    //!
322    //! The purpose of this module is to alleviate imports of many common types:
323    //!
324    //! ```
325    //! # #![allow(unused_imports)]
326    //! use yew::prelude::*;
327    //! ```
328
329    #[cfg(feature = "csr")]
330    pub use crate::app_handle::AppHandle;
331    pub use crate::callback::{Callback, CallbackRef, CallbackRefMut};
332    pub use crate::context::{ContextHandle, ContextProvider};
333    pub use crate::events::*;
334    pub use crate::functional::*;
335    pub use crate::html::{
336        create_portal, BaseComponent, Children, ChildrenWithProps, Classes, Component, Context,
337        Html, HtmlResult, NodeRef, Properties,
338    };
339    pub use crate::macros::{classes, html, html_nested};
340    pub use crate::suspense::Suspense;
341    pub use crate::virtual_dom::AttrValue;
342}
343
344pub use self::prelude::*;
yew/lib.rs

yew/
lib.rs
