yewstack · siku2 · Nov 21, 2020 · Oct 12, 2020 · Oct 12, 2020 · Oct 12, 2020
diff --git a/docs/concepts/components/children.md b/docs/concepts/components/children.md
@@ -0,0 +1,255 @@
+---
+title: Children
+description: 
+---
+
+## General usage
+
+_Most of the time,_ when allowing a component to have children, you don't care 
+what type of children the component has. In such cases, the below example will
+suffice.
+
+```rust
+use yew::prelude::*;
+
+#[derive(Properties, Clone)]
+pub struct ListProps {
+	#[prop_or_default]
+	pub children: Children,
+}
+
+pub struct List {
+	props: ListProps,
+}
+
+impl Component for List {
+	type Properties = ListProps;
+	// ...
+
+	fn view(&self) -> Html {
+		html! {
+			<div class="list">
+				{ for self.props.children.iter() }
+			</div>
+		}
+	}
+}
+```
+
+## Advanced usage
+
+There are some cases where you wouldn't want to use the `Children` type
+and instead use an alternative method:
+
+ - You want to only allow components of a specific type to be used as children for your component.
+
+ - You want to share state between a component and its children.
+
+### Typed children
+
+In cases where you want one type of component to be passed as children to your component,
+you can use `yew::html::ChildrenWithProps<T>`.
+
+```rust
+use yew::prelude::*;
+use yew::html::ChildrenWithProps;
+
+// ...
+
+#[derive(Properties, Clone)]
+pub struct ListProps {
+	#[prop_or_default]
+	pub children: ChildrenWithProps<Item>,
+}
+
+pub struct List {
+	props: ListProps,
+}
+
+impl Component for ListProps {
+	type Properties = ListProps;
+	// ...
+
+	fn view(&self) -> Html {
+		html! {
+			<div class="list">
+				{ for self.props.children.iter() }
+			</div>
+		}
+	}
+}
+```
+
+Of course, sometimes you might need to restrict the children to a few different
+components. In these cases, you have to get a little more hands-on with Yew.
+
+The `derive_more` crate is used here for better ergonomics. If you don't want
+to use it, replace `ItemPropVariants` with this:
+
+```rust
+#[derive(Clone)]
+pub enum ItemPropVariants {
+	MyFirstComponent(MyFirstComponentProps),
+	MySecondComponent(MySecondComponentProps),
+}
+
+impl From<MyFirstComponentProps> for ItemPropVariants {
+	fn from(props: MyFirstComponentProps) -> Self {
+		Self::MyFirstComponent(props)		
+	}
+}
+
+impl From<MySecondComponentProps> for ItemPropVariants {
+	fn from(props: MySecondComponentProps) -> Self {
+		Self::MySecondComponent(props)
+	}
+}
+```
+
+```rust
+use yew::prelude::*;
+use yew::html::ChildrenRenderer;
+use yew::virtual_dom::{ VChild, VComp };
+
+// ...
+
+#[derive(Clone, derive_more::From)]
+pub enum ItemPropVariants {
+	MyFirstComponent(MyFirstComponentProps),
+	MySecondComponent(MySecondComponentProps),
+}
+
+#[derive(Clone)]
+pub struct Item {
+	props: ItemPropVariants,
+}
+
+impl<CHILD> From<VChild<CHILD>> for Item
+where
+	CHILD: Component,
+	CHILD::Properties: Into<ItemPropVariants>,
+{
+	fn from(vchild: VChild<CHILD>) -> Self {
+		Item {
+			props: vchild.props.into(),
+		}
+	}
+}
+
+impl Into<Html> for Item {
+	fn into(self) -> Html {
+		match self.props {
+			ItemPropVariants::MyFirstComponent(props) => {
+				VComp::new::<MyFirstComponent>(props, NodeRef::default(), None).into()
+			}
+			ItemPropVariants::MySecondComponent(props) => {
+				VComp::new::<MySecondComponent>(props, NodeRef::default(), None).into()
+			}
+		}
+	}
+}
+
+#[derive(Properties, Clone)]
+pub struct ListProps {
+	#[prop_or_default]
+	pub children: ChildrenRenderer<Item>,
+}
+
+pub struct List {
+	props: ListProps,
+}
+
+impl Component for List {
+	type Properties = ListProps;
+	// ...
+
+	fn view(&self) -> Html {
+		html! {
+			<div class="list">
+				{ for self.props.children.iter() }
+			</div>
+		}
+	}
+}
+```
+
+Heres a run down of whats happening:
+
+This segment here defines the different types of properties that children
+components can have. Additionally, it derives `derive_more::From`, which
+implements `From<MyFirstComponentProps>` and `From<MySecondComponentProps>` for
+us!
+
+```rust
+#[derive(Clone, derive_more::From)]
+pub enum ItemPropVariants { /* ... */ }
+```
+
+Next, we use create this wrapper:
+
+```rust
+#[derive(Clone)]
+pub struct Item {
+	props: ItemPropVariants,
+}
+```
+
+Then, we implement `From<VChild<CHILD>>` for our wrapper, where `CHILD`:
+
+ - Implements `Component`
+
+ - Has a `Self::Properties` value that implements `Into<ItemPropVariants>`.
+
+This tells Yew how to handle converting a virtual DOM child into our wrapper!
+
+```rust
+impl<CHILD> From<VChild<CHILD>> for Item
+where
+	CHILD: Component,
+	CHILD::Properties: Into<ItemPropVariants>,
+{ /* ... */ }
+```
+
+Finally, we implement `Into<Html>` for our wrapper, allowing it to be rendered!
+
+```rust
+impl Into<Html> for Item { /* ... */ }
+```
+
+### Sharing properties
+
+This use case is mostly helpful for library developers, as you may want to
+share state between parent and child components without causing difficulty for
+users of your library.
+
+```rust
+// ... See the multiple typed children example ...
+
+#[derive(Properties, Clone)]
+pub struct ListProps {
+	#[prop_or_default]
+	pub children: ChildrenRenderer<Item>,
+}
+
+pub struct List {
+	props: ListProps,
+}
+
+impl Component for List {
+	type Properties = ListProps;
+	// ...
+
+	fn view(&self) -> Html {
+		html! {
+			<div class="list">
+				{
+					for self.props.children.iter().enumerate().map(|(i, mut item)| {
+						item.props.value = format!("#{}", i);
+						item
+					})
+				}
+			</div>
+		}
+	}
+}
+```
diff --git a/docs/concepts/components/properties.md b/docs/concepts/components/properties.md
@@ -16,9 +16,6 @@ Types for which you derive `Properties` must also implement `Clone`.
 
 ### Field attributes
 
-When deriving `Properties`, all fields are required by default.
-The following attributes allow you to give your props initial values which will be used unless they're set to another value.
-
 :::tip
 Attributes aren't visible in Rustdoc generated documentation.
 The docstrings of your properties should mention whether a prop is optional and if it has a special default value.

diff --git a/website/sidebars.json b/website/sidebars.json
@@ -25,6 +25,7 @@
           "concepts/components",
           "concepts/components/callbacks",
           "concepts/components/properties",
+          "concepts/components/children",
           "concepts/components/refs"
         ]
       },