diff --git a/plugins/ui/docs/components/fragment.md b/plugins/ui/docs/components/fragment.md new file mode 100644 index 000000000..8d6436ba3 --- /dev/null +++ b/plugins/ui/docs/components/fragment.md @@ -0,0 +1,38 @@ +# Fragment + +The `fragment` component allows you to group multiple elements without adding extra nodes to the DOM. This is especially useful when you need to return several elements but want to avoid wrapping them in an additional element. By using `fragment`, you can maintain a clean DOM tree and prevent unnecessary nesting. + +## Example + +```python +from deephaven import ui + +my_fragment = ui.fragment(ui.text("Child 1"), ui.text("Child 2")) +``` + +## Rendering a List + +When rendering multiple elements in a loop, ensure each fragment has a unique key. This is crucial if array items might be inserted, deleted, or reordered. + +```python +from deephaven import ui + + +@ui.component +def ui_fragment_list(): + children = [] + + for i in range(1, 4): + children.append(ui.fragment(ui.text(f"Child {i}"), key=i)) + + return ui.column(*children) + + +my_fragment = ui_fragment_list() +``` + +## API Reference + +```{eval-rst} +.. dhautofunction:: deephaven.ui.fragment +``` \ No newline at end of file diff --git a/plugins/ui/src/deephaven/ui/components/fragment.py b/plugins/ui/src/deephaven/ui/components/fragment.py index 1086407a0..f604c6d11 100644 --- a/plugins/ui/src/deephaven/ui/components/fragment.py +++ b/plugins/ui/src/deephaven/ui/components/fragment.py @@ -2,9 +2,10 @@ from typing import Any from .basic import component_element +from ..elements import Element -def fragment(*children: Any, key: str | None = None): +def fragment(*children: Any, key: str | None = None) -> Element: """ A React.Fragment: https://react.dev/reference/react/Fragment. Used to group elements together without a wrapper node. @@ -12,5 +13,8 @@ def fragment(*children: Any, key: str | None = None): Args: *children: The children in the fragment. key: A unique identifier used by React to render elements in a list. + + Returns: + The rendered fragment element. """ return component_element("Fragment", children=children, key=key)