Container¶

The Container element extends Card to support show/hide toggling without a full page refresh. Use it for progressive disclosure — revealing additional content when a user clicks a button.

Container Class¶

Container ¶

Container(title: str, content: List[Union[Element, Row]], subtitle: str = '', description: str = '', _id: Optional[str] = None, show_description: bool = True, page_update: Optional[Callable] = None, disable_next: bool = False, updater_text: Optional[str] = None, filters: Optional[List[InputElement]] = None, filter_update: Optional[Callable] = None, show_comments: bool = False, show_export: bool = False, show_share: bool = False, size: DrilldownSize = DrilldownSize.MEDIUM, visible: bool = False, on_close: Union[PageUpdateCallback, ContainerToggleCallback, None] = None)

A Container is a special type of Card that is rendered as a modal in the UI.

Parameters:

size (DrilldownSize, default: MEDIUM ) –

The size of the modal. See :class:~virtualitics_sdk.page.drilldown.DrilldownSize.
visible (bool, default: False ) –

Whether the modal is currently visible in the UI. If initialized with true, the container will render open as soon as it appears on the page.
on_close (Union[PageUpdateCallback, ContainerToggleCallback, None], default: None ) –

A callback function to be executed when the container is closed. The default_container_on_close helper can be used to easily create a callback that sets the container's visibility to False. This is called when a user clicks the X button, or clicks outside of the modal in the UI. A "Cancel" button must be added explicitly to the Container's content. EXAMPLE: .. code-block:: python from virtualitics_sdk import ( Button, ButtonType, Container, Dropdown, RichText, Row, StoreInterface, default_container_on_close, ) # Define callbacks to show and hide the modal @page_update_callback async def show_modal(store_interface: StoreInterface): page = store_interface.get_page() card = page.get_card_by_id("my-modal") if isinstance(card, Container): card.visible = True store_interface.update_page(page) @page_update_callback async def close_modal(store_interface: StoreInterface): page = store_interface.get_page() card = page.get_card_by_id("my-modal") if isinstance(card, Container): card.visible = False store_interface.update_page(page) # Create a button to open the modal show_button = Button(title="Show Modal", on_click=show_modal, button_type=ButtonType.PAGE_UPDATE) # Define the content for the modal modal_content = [ RichText("This is a modal."), Dropdown(options=["A", "B", "C"], title="My Dropdown"), Row([Button(title="Close", on_click=close_modal, button_type=ButtonType.PAGE_UPDATE)]), ] # Create the Container my_modal = Container( title="My Modal", _id="my-modal", content=modal_content, visible=False, on_close=default_container_on_close("my-modal"), )

set_visibility ¶

set_visibility(visible: bool)

Sets the visiblity of the Container. Uses force_update to account for cases where the front-end only container toggle was used elsewhere.

Basic Usage¶

from virtualitics_sdk import Container, Button
from virtualitics_sdk.types.callbacks import ContainerToggleCallback

# Create a container (hidden by default)
details = Container(
    id="detail_panel",
    title="Additional Details",
    visible=False
)
details.add_content([
    RichText("This content is revealed when the user clicks the button.")
])

# Button to show the container
show_btn = Button(
    id="show_btn",
    title="Show Details",
    show_confirmation=False,
    on_click=ContainerToggleCallback(
        visible=True,
        container_id="detail_panel"
    )
)

ContainerToggleCallback¶

Use ContainerToggleCallback to toggle container visibility. See the Callbacks Reference for the full API.

The container_id parameter accepts the container's ID with or without the card/ prefix — it is added automatically if missing.

Show and Hide¶

Use two buttons to toggle visibility in both directions:

from virtualitics_sdk import Container, Button, Section, Card
from virtualitics_sdk.types.callbacks import ContainerToggleCallback

container = Container(
    id="advanced_options",
    title="Advanced Options",
    visible=False
)
container.add_content([
    NumericSlider(id="epochs", title="Epochs", min_value=1, max_value=100, default=10),
    NumericSlider(id="lr", title="Learning Rate", min_value=0.001, max_value=1.0, default=0.01),
])

show_btn = Button(
    id="show_advanced",
    title="Show Advanced",
    show_confirmation=False,
    on_click=ContainerToggleCallback(visible=True, container_id="advanced_options")
)

hide_btn = Button(
    id="hide_advanced",
    title="Hide Advanced",
    show_confirmation=False,
    on_click=ContainerToggleCallback(visible=False, container_id="advanced_options")
)

Section(
    title="Configuration",
    cards=[
        Card(title="Settings", content=[show_btn, hide_btn]),
        container
    ]
)

Container with Close Callback¶

Containers support an optional on_close callback that fires when the container is hidden:

from virtualitics_sdk.types.callbacks import page_update_callback

@page_update_callback
async def on_container_close(store_interface):
    """Called when the container is closed."""
    page = await store_interface.get_page()
    status = page.get_element_by_id("status_text")
    status.content = "Advanced options hidden"

container = Container(
    id="closable_panel",
    title="Panel",
    visible=True,
    on_close=on_container_close
)

Container vs Card¶

Feature	Card	Container
Holds elements	Yes	Yes
Always visible	Yes	Toggleable
Toggle without refresh	No	Yes
Close callback	No	Yes

Use Card for content that should always be visible. Use Container for optional/advanced content the user can reveal on demand.

Best Practices¶

Start hidden: Use visible=False for optional content
Clear labels: Make the toggle button text indicate what will be shown
Don't nest deeply: Avoid putting containers inside containers
Keep it lightweight: Containers are for progressive disclosure, not for hiding heavy content