# Illustrated Message

An illustrated message displays an illustration along with a message, typically used for empty states or error pages.

## Example

```python
from deephaven import ui

my_illustrated_message_basic = ui.illustrated_message(
    ui.icon("vsError"),
    ui.heading("Access denied"),
    ui.content("You do not have permissions to access this page."),
)
```

## UI recommendations

Recommendations for creating an illustrated message:

1. The message should be concise and, if applicable, describe the next step a user can take.
2. The heading should be no longer than 6 words and should not be a replacement for the message text.
3. Use sentence case for the heading and message text.
4. Use illustrations that are relevant to the message and help convey the context effectively.
5. Reserve illustrated messages for situations where they add value and clarity, rather than using them for minor notifications or messages.

## Content

An illustrated message is made up of three parts: an illustration, a heading, and a body.

You can populate these sections by providing the following components as children: an `ui.icon` for the illustration, a `ui.heading` for the heading, and `ui.content` for the body.

```python
from deephaven import ui


my_illustrated_message_content_example = ui.illustrated_message(
    ui.icon("vsWarning"),
    ui.heading("Invalid input"),
    ui.content("No special characters allowed."),
)
```

## Labeling

If the heading of an illustrated message isn’t specified, set the `aria-label` prop for accessibility purposes.

```python
from deephaven import ui


my_illustrated_message_labeling_example = ui.illustrated_message(
    ui.icon("vsWorkspaceTrusted", aria_label="Trusted Workspace")
)
```

## Placeholder

Using an illustrated message as a placeholder for a table or list can clearly indicate the absence of data and provide context-specific guidance.

```python
from deephaven import ui
import deephaven.plot.express as dx

_stocks = dx.data.stocks()


@ui.component
def illustrated_message_placeholder_example():
    filter, set_filter = ui.use_state("")
    return [
        ui.text_field(
            value=filter, label="Sym Filter", is_required=True, on_change=set_filter
        ),
        ui.illustrated_message(
            ui.icon("vsFilter"),
            ui.heading("Filter required"),
            ui.content("Enter a filter to display filtered table"),
            width="100%",
        )
        if filter == ""
        else _stocks.where(f"Sym=`{filter.upper()}`"),
    ]


my_illustrated_message_placeholder_example = illustrated_message_placeholder_example()
```

## API reference

An IllustratedMessage displays an illustration and a message, usually for an empty state or an error page.

**Returns:** `Element` The rendered IllustratedMessage component.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "illustrated_message", "parameters": [{"name": "*children", "type": "Any", "description": "The content of the IllustratedMessage which consist of three areas: an illustration, a title, and a body."}, {"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 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 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 main 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 alignItems 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": "Species 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": "When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides 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 position.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The top position of the element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The bottom position of the element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The left position of the element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The right position of the element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The logical start position of the element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The logical end position of the element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stacking order for the element", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Hides the element.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "Set the CSS className for the element. Only use as a last resort. Use style props instead.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "Set the inline style for the element. Only use as a last resort. Use style props instead.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />