Let a component declare children: Vec<Element> as an alternative to Element

Closes the gap in #1177 ("Iterable Children"): today the
only way to get a caller's children as independent, individually-wrappable
values is a hand-built Vec<Element> field populated with explicit vec![]/
rsx!{} ceremony at every call site (the issue's own documented workaround).
Natural rsx! composition (bare children, for loops, if chains) only ever
produces one opaque merged Element.

This makes both declared shapes accept the exact same call-site syntax, with
zero change to how a caller writes children:

    ListItem {
        label: "Phone",
        "555-1234"
        "555-5678"
    }

works identically whether ListItem declares `children: Element` (merged, as
today) or `children: Vec<Element>` (one entry per top-level child, for/if
flattened to however many elements they actually produce).

Mechanism: `rsx!`'s component-children codegen (dioxus-rsx's component.rs)
now always compiles a component's children into a Vec<Element> - each
non-control-flow root becomes its own standalone single-root template
(TemplateBody::to_vec_tokens, reusing the existing single-Element codegen
unchanged), a `for` root recurses into its body and flat_maps per iteration,
and an `if`/`else` chain unifies its branches to Vec<Element> directly
(IfChain::to_vec_tokens) instead of merging through IntoDynNode. The macro
has no visibility into the callee's declared field type (macros expand
before type-checking), so it can't choose per-callee - instead the callee
side resolves it: dioxus-core-macro now forces the `children` field to
always go through SuperInto (like #[props(into)]) regardless of whether the
struct author wrote #[props(into)], and dioxus_core::properties gains
SuperFrom<Vec<Element>, _> impls for both `Element` and `Option<Element>`
that merge the vec back into one node through the same dynamic-node-slot
machinery a `for` loop's own output already uses (unwrapping directly for
the 1-element case, so the common single-child path produces the exact same
VNode shape as before).

The two hand-rolled Properties implementations in the whole workspace that
predate the derive macro's current shape (Portal, SuspenseBoundary) had
exact-type `children: Element` setters that would otherwise be the one place
still broken by this - both updated to accept `impl SuperInto<Element, M>`
too, mirroring what their own `fallback`-style setters already did.

Verified via packages/core/tests/vec_children.rs (single/multiple/nested
for+if/empty-default, both Element and Option<Element> targets), the full
existing dioxus-core/dioxus-rsx/dioxus-core-macro/dioxus-html/dioxus-hooks/
dioxus-ssr/dioxus test suites (all green, including doctests with
--all-features), cargo fmt --all --check, and cargo clippy --all-features
--all-targets -- -D warnings on every crate this touches - no regressions.

Author: tdymel

packages/core-macro/src/props/mod.rs

@@ -172,7 +172,10 @@ mod util {
 }
 
 mod field_info {
-    use crate::props::{looks_like_store_type, looks_like_write_type, type_from_inside_option};
+    use crate::props::{
+        looks_like_store_type, looks_like_write_type, type_from_inside_option,
+        type_is_vec_of_elements,
+    };
     use proc_macro2::TokenStream;
     use quote::{format_ident, quote};
     use syn::spanned::Spanned;
@@ -204,10 +207,24 @@ mod field_info {
                 let strip_option_auto = builder_attr.strip_option
                     || !builder_attr.ignore_option && type_from_inside_option(&field.ty).is_some();
 
-                // children field is automatically defaulted to an empty VNode unless it is marked as optional (in which case it defaults to None)
-                if name == "children" && !strip_option_auto {
-                    builder_attr.default =
-                        Some(syn::parse(quote!(dioxus_core::VNode::empty()).into()).unwrap());
+                if name == "children" {
+                    // The call site always builds a `Vec<Element>` (see `dioxus-rsx`'s
+                    // `component.rs`), so the setter takes `impl SuperInto<_>` like
+                    // `#[props(into)]` does - that's what lets the field declare either
+                    // `Element` or `Vec<Element>` and still accept the same call-site syntax.
+                    builder_attr.auto_into = true;
+
+                    // children is automatically defaulted to an empty VNode - or an empty Vec,
+                    // for a `children: Vec<Element>` field - unless it is marked as optional (in
+                    // which case it defaults to None)
+                    if !strip_option_auto {
+                        let default = if type_is_vec_of_elements(&field.ty) {
+                            quote!(::std::vec::Vec::new())
+                        } else {
+                            quote!(dioxus_core::VNode::empty())
+                        };
+                        builder_attr.default = Some(syn::parse(default.into()).unwrap());
+                    }
                 }
 
                 // String fields automatically use impl Display
@@ -497,6 +514,31 @@ mod field_info {
     }
 }
 
+/// Whether this is a `Vec<Element>`, however `Vec` and `Element` are spelled or pathed
+fn type_is_vec_of_elements(ty: &Type) -> bool {
+    let Type::Path(type_path) = ty else {
+        return false;
+    };
+
+    let Some(seg) = type_path.path.segments.last() else {
+        return false;
+    };
+
+    if seg.ident != "Vec" {
+        return false;
+    }
+
+    let Some(Type::Path(inner)) = extract_inner_type_from_segment(seg) else {
+        return false;
+    };
+
+    inner
+        .path
+        .segments
+        .last()
+        .is_some_and(|seg| seg.ident == "Element")
+}
+
 fn type_from_inside_option(ty: &Type) -> Option<&Type> {
     let Type::Path(type_path) = ty else {
         return None;

packages/core/src/portal.rs

@@ -93,11 +93,19 @@ impl<__children> PortalPropsBuilder<((), __children)> {
 
 #[allow(dead_code, non_camel_case_types, missing_docs)]
 impl<__target> PortalPropsBuilder<(__target, ())> {
+    /// Takes `impl SuperInto<Element, _>` rather than a bare `Element`, mirroring what
+    /// `#[derive(Props)]` now generates for every `children: Element` field - the call site
+    /// compiles children to a `Vec<Element>` (see
+    /// [`crate::properties::VecElementFromMarker`]), so a bare `Element` here wouldn't accept
+    /// them.
     #[allow(clippy::type_complexity)]
-    pub fn children(self, children: Element) -> PortalPropsBuilder<(__target, (Element,))> {
+    pub fn children<__Marker>(
+        self,
+        children: impl crate::SuperInto<Element, __Marker>,
+    ) -> PortalPropsBuilder<(__target, (Element,))> {
         let (target, _) = self.fields;
         PortalPropsBuilder {
-            fields: (target, (children,)),
+            fields: (target, (children.super_into(),)),
             _phantom: self._phantom,
         }
     }
@@ -147,9 +155,9 @@ impl<RenderFn, ComponentMarker, __target>
     PortalComponentBuilder<RenderFn, ComponentMarker, (__target, ())>
 {
     #[allow(clippy::type_complexity)]
-    pub fn children(
+    pub fn children<__Marker>(
         self,
-        children: Element,
+        children: impl crate::SuperInto<Element, __Marker>,
     ) -> PortalComponentBuilder<RenderFn, ComponentMarker, (__target, (Element,))> {
         PortalComponentBuilder {
             render_fn: self.render_fn,

packages/core/src/properties.rs

@@ -356,6 +356,48 @@ where
     }
 }
 
+/// Marker used to merge the `Vec<Element>` an `rsx!` body compiles its children to back into a
+/// single [`Element`], for a component that declares `children: Element`. Together with the
+/// `Vec<Element>` shape passing straight through, this is what makes both declarations accept the
+/// exact same call-site syntax.
+#[doc(hidden)]
+pub struct VecElementFromMarker;
+
+/// `None` only for a genuinely empty list, never for a render error - `IntoDynNode for Element`
+/// already treats an `Err` as "nothing" rather than propagating it
+fn merge_vnodes(input: Vec<Element>) -> Option<VNode> {
+    let mut nodes: Vec<VNode> = input.into_iter().map(IntoVNode::into_vnode).collect();
+    match nodes.len() {
+        0 => None,
+        // One child, the common case, keeps exactly the VNode shape `children: Element` has
+        1 => Some(nodes.pop().unwrap()),
+        // 2+ separately built VNodes share no static Template, so they can only be combined at
+        // runtime, through the same dynamic-node slot a `for` loop's output already uses
+        _ => {
+            use crate::view::{ViewExt, dynamic_node_builder};
+            Some(dynamic_node_builder::<_, ()>(DynamicNode::Fragment(nodes)).into_vnode())
+        }
+    }
+}
+
+impl SuperFrom<Vec<Element>, VecElementFromMarker> for Element {
+    fn super_from(input: Vec<Element>) -> Self {
+        // An empty list lands on `VNode::empty()`, the `children: Element` default
+        Ok(merge_vnodes(input).unwrap_or_default())
+    }
+}
+
+/// Marker used to merge a `Vec<Element>` into `Option<Element>`, for a component whose `children`
+/// is itself optional - `None` for an empty list, same as that field's own default.
+#[doc(hidden)]
+pub struct VecElementFromOptionMarker;
+
+impl SuperFrom<Vec<Element>, VecElementFromOptionMarker> for Option<Element> {
+    fn super_from(input: Vec<Element>) -> Self {
+        merge_vnodes(input).map(Ok)
+    }
+}
+
 /// Marker used to convert `&str` into `Option<String>` through [`SuperFrom`].
 #[doc(hidden)]
 pub struct OptionStringFromMarker;

packages/core/src/suspense/component.rs

@@ -105,9 +105,9 @@ impl<RenderFn, ComponentMarker, __fallback>
 {
     #[allow(clippy::type_complexity)]
     #[doc(hidden)]
-    pub fn children(
+    pub fn children<__Marker>(
         self,
-        children: Element,
+        children: impl SuperInto<Element, __Marker>,
     ) -> SuspenseBoundaryComponentBuilder<RenderFn, ComponentMarker, (__fallback, (Element,))> {
         SuspenseBoundaryComponentBuilder {
             render_fn: self.render_fn,
@@ -175,11 +175,11 @@ impl<__children> SuspenseBoundaryPropsBuilder<((Callback<SuspenseContext, Elemen
 impl<__fallback> SuspenseBoundaryPropsBuilder<(__fallback, ())> {
     #[allow(clippy::type_complexity)]
     #[doc(hidden)]
-    pub fn children(
+    pub fn children<__Marker>(
         self,
-        children: Element,
+        children: impl SuperInto<Element, __Marker>,
     ) -> SuspenseBoundaryPropsBuilder<(__fallback, (Element,))> {
-        let children = (children,);
+        let children = (SuperInto::super_into(children),);
         let (fallback, _) = self.fields;
         SuspenseBoundaryPropsBuilder {
             owner: self.owner,