Button¶

Buttons are interactive elements that trigger actions when clicked. They support multiple callback types for different interaction patterns.

Button Class¶

Button ¶

Button(*, title, confirmation_text=None, label=None, icon=None, icon_position='prefix', on_click=None, style=ButtonStyle.SECONDARY, color=EonColor.ACCENT, rounded=False, horizontal_position=ElementHorizontalPosition.LEFT, vertical_position=ElementVerticalPosition.TOP, tooltip=None, open_new_tab=False, show_confirmation=True, display_text_only=False, reference_id='', **kwargs)

A configurable Button Element.

Parameters:

title (str) –

The title of the element. Also used as the default button label if label is not provided.
confirmation_text (Optional[str], default: None ) –

Optional confirmation text displayed in the element description area. If provided, it overrides description.
label (Optional[str], default: None ) –

The text displayed on the button face. Defaults to title if omitted.
icon (AllowedIcons | None, default: None ) –

Optional icon name. Must be a valid entry in virtualitics_sdk.icons.ALL_ICONS.
on_click (Optional[Callback], default: None ) –

Callback executed when the button is clicked. Callbacks that require a function need to be instantiated using their corresponding decorator. Callback types include - StandardEventCallback (@standard_event_callback): Arbitrary changes can be made to the page without re-rendering, returns text. - PageUpdateCallback (@page_update_callback): Arbitrary changes can be made to the page, automatically re-renders all changed elements. - DrilldownCallback (@drilldown_callback(drilldown_type, drilldown_size): Returns a Card with arbitrary elements, used for ephemeral modal display. - ContainerToggleCallback(no decorator): Toggles the visibility of a Container element without requiring a page update. - AssetDownloadCallback(no decorator): Allows for download of specified assets. For standard events and page updates, the function should be a callable with the following signature .. code-block:: python @page_update_callback async def callback(store_interface: StoreInterface) -> None ... Drilldowns Drilldown callbacks have a more complex signature / usage than the standard page update / event functions. The callback is persisted and invoked by the platform at runtime. It should be a callable with the following signature .. code-block:: python @drilldown_callback(drilldown_type=DrilldownType.FAST_MODAL, drilldown_size=DrilldownSize.SHEET) async def callback( card: "Card", input_data: dict[str, str | float | int], store_interface: "DrilldownStoreInterface", ) -> None: ... Arguments passed to the decorator - drilldown_type: Type of the drilldown (e.g., FAST_MODAL, POPOVER) - drilldown_size: Size hint for the drilldown surface (e.g., SMALL, MEDIUM, SHEET) Arguments passed to the function - card: A mutable container representing the drilldown surface. Add elements (e.g., RichText, Table, Chart) with card.add_content([...]). You may also set layout/behavior, e.g.: card.drilldown_type = drilldown_type.value and card.drilldown_size = drilldown_size.value (if supported). - input_data: A dictionary of primitive values (str | float | int) derived from the current context (e.g., selection, row details, or filter state). Use this to parameterize the drilldown (populate text, filter tables, etc.). - store_interface: A state helper scoped to the drilldown. The exact API depends on DrilldownStoreInterface. Return value - The return value is ignored; render by mutating card (add content, set type/size). Side effects & lifecycle - The callback is serialized during _save() and stored server-side. At click time, the platform deserializes and executes it. Content guidelines - Add content via card.add_content([Element,...]). Supported elements include RichText, Table, and other virtualitics_sdk elements. EXAMPLE .. code-block:: python from typing import Any import pandas as pd from virtualitics_sdk import RichText, Table from virtualitics_sdk.drilldown import DrilldownType, DrilldownSize from virtualitics_sdk.drilldown import DrilldownStoreInterface def example_callback_small( card: "Card", input_data: dict[str, str | float | int], store_interface: DrilldownStoreInterface, drilldown_type: DrilldownType = DrilldownType.MODAL, drilldown_size: DrilldownSize = DrilldownSize.SMALL, ) -> None: # Build tabular content df = pd.DataFrame([ {"column_1": 1, "column_2": "A", "column_3": 100.0}, {"column_1": 2, "column_2": "B", "column_3": 200.0}, {"column_1": 3, "column_2": "C", "column_3": 300.0}, ]) # Compose content from input_data plus a table content: list[Any] = [RichText(title=k, content=v) for k, v in input_data.items()] content.append(Table(content=df, title="Example Table")) # Render into the drilldown card.add_content(content) card.drilldown_type = drilldown_type.value
style (Optional[ButtonStyle], default: SECONDARY ) –

Visual style of the button (primary, secondary, tertiary, ghost). Defaults to ButtonStyle.SECONDARY.
color (Optional[EonColor], default: ACCENT ) –

Color styling for the button. Supports base palette colors: accent, amber, blue, cyan, fuchsia, green, grass, indigo, neutral, orange, purple, red, teal, violet, yellow, alert. Defaults to EonColor.ACCENT.
rounded (bool, default: False ) –

If True, displays the button with rounded corners. Particularly useful with tertiary style for chip-like appearance. Defaults to False.
horizontal_position (ElementHorizontalPosition, default: LEFT ) –

Horizontal alignment of the element within its card. Defaults to ElementHorizontalPosition.LEFT.
vertical_position (ElementVerticalPosition, default: TOP ) –

Vertical alignment of the element within its card. Defaults to ElementVerticalPosition.TOP.
tooltip (Optional[str], default: None ) –

Optional tooltip shown on hover.
open_new_tab (Optional[bool], default: False ) –

If True, standard buttons will open their link in a new tab (when applicable). Defaults to False.
show_confirmation (Optional[bool], default: True ) –

If True, buttons will display a confirmation dialog before executing their action. Defaults to True.
display_text_only (bool, default: False ) –

If True, renders the button as plain text instead of a clickable button. Useful for mixed button/text columns in tables. Defaults to False.
reference_id (Optional[str], default: '' ) –

A user-defined reference ID for the unique identification of Button element within the Page, defaults to ''.
kwargs –

Additional parameters: - description: Element description (ignored if confirmation_text is provided).

Basic Usage¶

from virtualitics_sdk import Button, ButtonStyle, ButtonColor

# Simple button
button = Button(
    id="my_button",
    title="Click Me",
    label="Submit",
    style=ButtonStyle.PRIMARY,
    color=ButtonColor.ACCENT
)

Button Styles¶

Buttons support three visual styles:

from virtualitics_sdk import ButtonStyle

# Primary - Most prominent
primary_btn = Button(
    title="Save",
    style=ButtonStyle.PRIMARY,
    color=ButtonColor.ACCENT
)

# Secondary - Standard appearance (default)
secondary_btn = Button(
    title="Cancel",
    style=ButtonStyle.SECONDARY,
    color=ButtonColor.NEUTRAL
)

# Ghost - Minimal appearance
ghost_btn = Button(
    title="Learn More",
    style=ButtonStyle.GHOST,
    color=ButtonColor.NEUTRAL
)

Button Colors¶

from virtualitics_sdk import ButtonColor

# Accent - Primary brand color
accent_btn = Button(title="Continue", color=ButtonColor.ACCENT)

# Neutral - Neutral/gray color
neutral_btn = Button(title="Cancel", color=ButtonColor.NEUTRAL)

# Alert - Warning/danger color
alert_btn = Button(title="Delete", color=ButtonColor.ALERT)

Icons¶

Add icons to buttons using icon names from virtualitics_sdk.icons.ALL_ICONS:

from virtualitics_sdk import Button

button = Button(
    title="Download",
    label="Download Report",
    icon="download",  # Icon name from ALL_ICONS
    style=ButtonStyle.PRIMARY
)

Callback Types¶

Buttons support five different callback types for different interaction patterns.

Standard Event Callback¶

Returns a text message without re-rendering the page. Useful for simple notifications.

from virtualitics_sdk import Button, StoreInterface
from virtualitics_sdk.types.callbacks import standard_event_callback

@standard_event_callback
async def handle_click(store_interface: StoreInterface) -> str:
    # Perform some action
    data = await store_interface.get_data("my_data")
    # Return success message
    return "Action completed successfully!"

button = Button(
    id="notify_btn",
    title="Notify Me",
    on_click=handle_click
)

Page Update Callback¶

Modifies the page and automatically re-renders all changed elements.

from virtualitics_sdk import Button, StoreInterface, RichText
from virtualitics_sdk.types.callbacks import page_update_callback

@page_update_callback
async def update_page(store_interface: StoreInterface) -> None:
    # Get the current page
    page = await store_interface.get_page()

    # Modify elements on the page
    text_elem = page.get_element_by_id("status_text")
    text_elem.content = "Updated at " + str(datetime.now())

    # Page will automatically re-render

button = Button(
    id="update_btn",
    title="Update Page",
    on_click=update_page
)

Drilldown Callback¶

Opens a modal or popover with custom content. Great for showing detailed information.

from virtualitics_sdk import Button, Card, Table, RichText
from virtualitics_sdk.page.drilldown import DrilldownType, DrilldownSize
from virtualitics_sdk.store.drilldown_store_interface import DrilldownStoreInterface
from virtualitics_sdk.types.callbacks import drilldown_callback

@drilldown_callback(
    drilldown_type=DrilldownType.FAST_MODAL,
    drilldown_size=DrilldownSize.LARGE
)
async def show_details(
    card: Card,
    input_data: dict[str, str | float | int],
    store_interface: DrilldownStoreInterface
) -> None:
    # Load data for the drilldown
    data = await store_interface.get_data("details")

    # Add content to the card
    card.add_content([
        RichText(content="## Detailed Information"),
        Table(data=data)
    ])

    # Set drilldown properties
    card.drilldown_type = DrilldownType.FAST_MODAL.value
    card.drilldown_size = DrilldownSize.LARGE.value

button = Button(
    id="details_btn",
    title="View Details",
    on_click=show_details
)

Drilldown Types¶

from virtualitics_sdk.page.drilldown import DrilldownType, DrilldownSize

# Fast Modal - Quick loading modal overlay
DrilldownType.FAST_MODAL

# Popover - Smaller popup near the button
DrilldownType.POPOVER

Drilldown Sizes¶

from virtualitics_sdk.page.drilldown import DrilldownSize

# Small, medium, large, or sheet (full height)
DrilldownSize.SMALL
DrilldownSize.MEDIUM
DrilldownSize.LARGE
DrilldownSize.SHEET

Container Toggle Callback¶

Toggles the visibility of a Container element without page refresh.

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

# Create a container
container = Container(
    id="details_container",
    title="Additional Details",
    content=[
        Card(
            title="Details",
            content=[RichText(content="Hidden content here")]
        )
    ],
    visible=False  # Start hidden
)

# Button to toggle visibility
toggle_button = Button(
    id="toggle_btn",
    title="Show/Hide Details",
    on_click=ContainerToggleCallback(
        visible=True,  # Set to True to show, False to hide
        container_id="details_container"
    )
)

Asset Download Callback¶

Triggers download of an asset (file).

from virtualitics_sdk import Button
from virtualitics_sdk.types.callbacks import AssetDownloadCallback

# Assuming you have an asset object
button = Button(
    id="download_btn",
    title="Download",
    label="Download Dataset",
    on_click=AssetDownloadCallback(),
    asset=my_asset,  # Asset object with id, type, label, name, time_created
    extension=".csv",
    mime_type="text/csv"
)

Confirmation Dialogs¶

By default, buttons show a confirmation dialog before executing their action. You can customize or disable this:

from virtualitics_sdk import Button

# Custom confirmation text
button_with_confirmation = Button(
    title="Delete",
    confirmation_text="Are you sure you want to delete this item?",
    show_confirmation=True,  # Default is True
    on_click=delete_callback
)

# No confirmation
button_no_confirmation = Button(
    title="Save",
    show_confirmation=False,
    on_click=save_callback
)

Tooltips¶

Add helpful tooltips that appear on hover:

button = Button(
    title="Submit",
    tooltip="Click to submit the form and process your request",
    on_click=submit_callback
)

Positioning¶

Control button placement within a card:

from virtualitics_sdk.elements.element import ElementHorizontalPosition, ElementVerticalPosition

button = Button(
    title="Action",
    horizontal_position=ElementHorizontalPosition.RIGHT,
    vertical_position=ElementVerticalPosition.BOTTOM,
    on_click=my_callback
)

Complete Example¶

from virtualitics_sdk import (
    App, Step, Page, Section, Card, Button, Table,
    ButtonStyle, ButtonColor, StoreInterface
)
from virtualitics_sdk.types.callbacks import page_update_callback, drilldown_callback
from virtualitics_sdk.page.drilldown import DrilldownType, DrilldownSize
import pandas as pd

class DataExplorerApp(App):
    class LoadData(Step):
        def run(self, flow_metadata):
            # Load initial data
            df = pd.DataFrame({
                'product': ['A', 'B', 'C'],
                'sales': [100, 200, 150]
            })
            self._outLink.data = df

            return Page(
                title="Data Explorer",
                sections=[
                    Section(
                        title="Data",
                        cards=[
                            Card(
                                title="Sales Data",
                                content=[
                                    Table(data=df),
                                    Button(
                                        id="refresh_btn",
                                        title="Refresh Data",
                                        label="Refresh",
                                        icon="refresh",
                                        style=ButtonStyle.PRIMARY,
                                        color=ButtonColor.ACCENT,
                                        on_click=self.refresh_data
                                    ),
                                    Button(
                                        id="details_btn",
                                        title="View Details",
                                        label="More Info",
                                        icon="info",
                                        style=ButtonStyle.SECONDARY,
                                        on_click=self.show_details
                                    )
                                ]
                            )
                        ]
                    )
                ]
            )

        @page_update_callback
        async def refresh_data(self, store_interface: StoreInterface) -> None:
            # Update the table with new data
            page = await store_interface.get_page()
            table = page.get_element_by_id("sales_table")

            # Fetch fresh data
            new_df = pd.DataFrame({
                'product': ['A', 'B', 'C', 'D'],
                'sales': [110, 210, 160, 90]
            })
            table.data = new_df

        @drilldown_callback(
            drilldown_type=DrilldownType.FAST_MODAL,
            drilldown_size=DrilldownSize.MEDIUM
        )
        async def show_details(
            self,
            card: Card,
            input_data: dict,
            store_interface
        ) -> None:
            from virtualitics_sdk import RichText

            card.add_content([
                RichText(content="""
                ## Sales Data Details

                This table shows product sales across all regions.
                Data is updated in real-time.
                """)
            ])

Reference ID¶

Use reference_id to uniquely identify buttons across your app:

button = Button(
    title="Submit",
    reference_id="submit_form_button",
    on_click=submit_callback
)

Best Practices¶

Clear Labels: Use descriptive button labels that clearly indicate the action
Appropriate Styles: Use PRIMARY for main actions, SECONDARY for secondary actions, GHOST for tertiary
Confirmation for Destructive Actions: Always use confirmation dialogs for delete/destructive operations
Loading States: For long-running operations, provide feedback through StandardEventCallback return messages
Icon Consistency: Use icons consistently across your app (same icon for same actions)
Drilldowns for Details: Use drilldown callbacks for showing additional information without navigating away
Container Toggles for Progressive Disclosure: Use container toggles to show/hide optional content

Callback Decorator Reference¶

All callback decorators and types are available from virtualitics_sdk.types.callbacks:

from virtualitics_sdk.types.callbacks import (
    standard_event_callback,
    page_update_callback,
    drilldown_callback,
    ContainerToggleCallback,
    AssetDownloadCallback
)