# Breadcrumbs

Breadcrumbs show hierarchy and navigational context for a user’s location within an application.

```python
from deephaven import ui


breadcrumbs_example = ui.view(
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
    ),
    width="100%",
)
```

![Breadcrumbs Basic Example](../_assets/breadcrumbs_basic.png)

## Content

`ui.breadcrumbs` accepts `item` elements as children, each with a `key` prop. Basic usage of breadcrumbs, seen in the example above, shows multiple items populated with a string.

## Events

Use the `on_action` prop to specify a callback to handle press events on items.

```python
from deephaven import ui


@ui.component
def breadcrumbs_action_example():
    selected, set_selected = ui.use_state("None")

    return (
        ui.view(
            ui.breadcrumbs(
                ui.item("Deephaven", key="deephaven"),
                ui.item("Products", key="products"),
                ui.item("Community Core", key="community_core"),
                on_action=set_selected,
            ),
            ui.text(f"{selected} clicked"),
            width="100%",
        ),
    )


my_breadcrumbs_action_example = breadcrumbs_action_example()
```

## Links

By default, interacting with an item in breadcrumbs triggers `on_action`. By passing the `href` prop to the `ui.item` component, items may also be links to another page or website. The target window to open the link in can be configured using the `target` prop.

```python
from deephaven import ui


breadcrumbs_link_example = ui.view(
    ui.breadcrumbs(
        ui.item(
            "Deephaven",
            key="deephaven",
            href="https://deephaven.io/",
            target="_blank",
        ),
        ui.item(
            "Community Core",
            key="community_core",
            href="https://deephaven.io/community/",
            target="_blank",
        ),
        ui.item(
            "Getting Started",
            key="getting_started",
            href="https://deephaven.io/core/docs/getting-started/quickstart/",
            target="_blank",
        ),
    ),
    width="100%",
)
```

## Size

The size of the breadcrumbs including spacing and layout can be set using the `size` prop. By default this is set to `"L"`.

```python
from deephaven import ui


breadcrumbs_size_example = ui.view(
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
    ),
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
        size="M",
    ),
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
        size="S",
    ),
    width="100%",
)
```

## Multiline

Use the `is_multiline` prop to place the last item below the other items. This adds emphasis to the current location as a page title or heading.

```python
from deephaven import ui


breadcrumbs_multiline_example = ui.view(
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
        is_multiline=True,
    ),
    width="100%",
)
```

## Root context

Some applications find that always displaying the root item is useful to orient users. Use the `show_root` prop to keeps the root visible when other items are truncated into the menu.

```python
from deephaven import ui


breadcrumbs_root_context_example = ui.view(
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
        ui.item("Getting Started", key="getting_started"),
        ui.item("Create Tables", key="create_tables"),
        show_root=True,
    ),
    width="300px",
)
```

## Disabled

Use the `is_disabled` prop to show items but indicate that navigation is not available. This can be used to maintain layout continuity.

```python
from deephaven import ui


breadcrumbs_disabled_example = ui.view(
    ui.breadcrumbs(
        ui.item("Deephaven", key="deephaven"),
        ui.item("Products", key="products"),
        ui.item("Community Core", key="community_core"),
        is_disabled=True,
    ),
    width="100%",
)
```

## Overflow behavior

Breadcrumbs collapses items into a menu when space is limited. It will only show a maximum of 4 visible items including the root and menu button, if either are visible.

If the root item cannot be rendered in the available horizontal space, it will be collapsed into the menu regardless of the `show_root` prop.

Note that the last breadcrumb item will automatically truncate with an ellipsis instead of collapsing into the menu.

```python
from deephaven import ui


@ui.component
def breadcrumbs_overflow_example():
    return [
        ui.view(
            ui.breadcrumbs(
                ui.item("Deephaven", key="deephaven"),
                ui.item("Products", key="products"),
                ui.item("Community Core", key="community_core"),
                ui.item("Getting Started", key="getting_started"),
                ui.item("Create Tables", key="create_tables"),
                show_root=True,
            ),
            border_width="thin",
            border_color="accent-400",
            width="100%",
        ),
        ui.view(
            ui.breadcrumbs(
                ui.item("Deephaven", key="deephaven"),
                ui.item("Products", key="products"),
                ui.item("Community Core", key="community_core"),
                ui.item("Getting Started", key="getting_started"),
                ui.item("Create Tables", key="create_tables"),
                show_root=True,
            ),
            border_width="thin",
            border_color="accent-400",
            width="200px",
        ),
        ui.view(
            ui.breadcrumbs(
                ui.item("Deephaven", key="deephaven"),
                ui.item("Products", key="products"),
                ui.item("Community Core", key="community_core"),
                ui.item("Getting Started", key="getting_started"),
                ui.item("Create Tables", key="create_tables"),
            ),
            border_width="thin",
            border_color="accent-400",
            width="100px",
        ),
    ]


my_breadcrumbs_overflow_example = breadcrumbs_overflow_example()
```

## Detailed example

Below is an example using the generated `tips` dataset from the Deephaven Express API. It allows you to explore the data in a hierarchical order of day, time, sex, and smoker status.

```python order=my_tips,_tips
import deephaven.plot.express as dx
from deephaven.table import Table
from deephaven import ui


@ui.component
def table_breadcrumb_filterer(
    table: Table, filter_columns: list[str], all_item_text="All"
):
    items, set_items = ui.use_state([ui.item(all_item_text)])
    option_column, set_option_column = ui.use_state(filter_columns[0])
    filters, set_filters = ui.use_state([])

    filtered_table = ui.use_memo(lambda: table.where(filters), [table, filters])
    column_value_table = ui.use_memo(
        lambda: filtered_table.select_distinct(option_column),
        [filtered_table, option_column],
    )
    column_values = ui.use_column_data(column_value_table)

    def handle_action(key):
        current_index = filter_columns.index(option_column)
        set_items(items + [ui.item(f"{key}", key=option_column)])
        if current_index < len(filter_columns) - 1:
            set_option_column(filter_columns[current_index + 1])
        set_filters(filters + [f"{option_column} == '{key}'"])

    def handle_back(key):
        if key not in filter_columns:
            set_items([ui.item(all_item_text)])
            set_option_column(filter_columns[0])
            set_filters([])
            return

        selected_index = filter_columns.index(key)
        set_items(items[: selected_index + 2])
        set_option_column(filter_columns[selected_index + 1])
        set_filters(filters[: selected_index + 1])

    show_filter = len(filters) < len(filter_columns)

    return ui.flex(
        ui.flex(
            ui.breadcrumbs(*items, show_root=True, on_action=handle_back, flex_grow=1),
            ui.view(
                ui.menu_trigger(
                    ui.action_button(f"Filter by {option_column}", ui.icon("filter")),
                    ui.menu(
                        *[ui.item(value) for value in column_values],
                        on_action=handle_action,
                    ),
                ),
            )
            if show_filter
            else None,
        ),
        filtered_table.view(
            formulas=["TotalBill", "Tip", "Size"] + filter_columns[len(filters) :]
        ),
        direction="column",
    )


_tips = dx.data.tips()
my_tips = table_breadcrumb_filterer(_tips, ["Day", "Time", "Sex", "Smoker"], "All Tips")
```

## API reference

Breadcrumbs show hierarchy and navigational context for a user's location within an application.

**Returns:** `Element` The rendered breadcrumbs element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "breadcrumbs", "parameters": [{"name": "*children", "type": "str | int | float | bool | BaseElement", "description": "The items to render within the breadcrumbs."}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the Breadcrumbs are disabled.", "default": "None"}, {"name": "size", "type": "Literal['S', 'M', 'L'] | None", "description": "The size of the breadcrumbs inlcuding spacing and layout.", "default": "None"}, {"name": "show_root", "type": "bool | None", "description": "Whether to always show the root item if the items are collapsed.", "default": "None"}, {"name": "is_multiline", "type": "bool | None", "description": "Whether the last item will be placed below other items.", "default": "None"}, {"name": "auto_focus_current", "type": "bool | None", "description": "Whether to autoFocus the last item.", "default": "None"}, {"name": "on_action", "type": "Callable[[str], None] | None", "description": "Handler that is called when an item is clicked.", "default": "None"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how much the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how much the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the align_items property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Specifies how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "The name of the grid area to place the element in.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "The name of the grid row to place the element in.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "The name of the grid row to start the element in.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "The name of the grid row to end the element in.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "The name of the grid column to place the element in.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "The name of the grid column to start the element in.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "The name of the grid column to end the element in.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin to apply around the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin to apply above the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin to apply below the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin to apply before the element.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin to apply after the element.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin to apply to the left and right of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin to apply to the top and bottom of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "Specifies how the element is positioned.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "A unique identifier for the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The details for the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />