Elements¶

Elements are UI components that make your apps interactive. They range from simple text displays to complex tables and visualizations.

Available Elements¶

Display Elements¶

Table: Display tabular data with sorting, filtering, and actions
PlotlyPlot: Interactive Plotly visualizations
RichText: Markdown-formatted text
Image: Display images
Infographic: Info cards with metrics

Input Elements¶

SingleDropdown: Select one option from a list
MultiDropdown: Select multiple options
TextInput: Free-text input
NumericSlider: Numeric value selection
NumericRange: Numeric range selection
DateTimeRange: Date/time range selection
Button: Interactive buttons with callbacks

Layout Elements¶

Dashboard: Multi-panel layouts
Row/Column: Grid-based layouts
Container: Show/hide content via toggle
Segmented Control: Tabbed views within a card
Accordion: Expand and collapse views

Data Elements¶

DataSource: Reference to external data connections

Element Base Class¶

Element ¶

Element(_type: ElementType, params: Dict[str, Any], content: Union[dict, list, str], title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, _id: str = '', label: str = '', placeholder: str = '', on_click: Union[DrilldownCallback, StandardEventCallback, PageUpdateCallback, None] = None, horizontal_position: ElementHorizontalPosition = ElementHorizontalPosition.LEFT, vertical_position: ElementVerticalPosition = ElementVerticalPosition.TOP, overflow_behavior: ElementOverflowBehavior = ElementOverflowBehavior.SCROLL, reference_id: Optional[str] = '')

An Element in the Virtualitics AI Platform.

Parameters:

_type (ElementType) –

The type of element.
params (Dict[str, Any]) –

The parameters for that element.
content (Union[dict, list, str]) –

The content of the element.
_id (str, default: '' ) –

The ID of the element, defaults to None.
title (str, default: '' ) –

The title of the element, defaults to ''.
description (str, default: '' ) –

The description of the element, defaults to ''.
show_title (bool, default: True ) –

Whether to show the title on the page when rendered, defaults to True.
show_description (bool, default: True ) –

Whether to show the description to the page when rendered, defaults to True.
label (str, default: '' ) –

The label of the element, defaults to ''.
placeholder (str, default: '' ) –

The placeholder of the element, defaults to ''.
on_click (Union[DrilldownCallback, StandardEventCallback, PageUpdateCallback, None], default: None ) –

Callback used for clickable elements, defaults to None.
horizontal_position (ElementHorizontalPosition, default: LEFT ) –

The horizontal position the element should be placed, defaults to ElementHorizontalPosition.LEFT
vertical_position (ElementVerticalPosition, default: TOP ) –

The vertical position the element should be placed, defaults to ElementVerticalPosition.TOP
overflow_behavior (ElementOverflowBehavior, default: SCROLL ) –

For supported elements, specifies how the platform will handle the overflow of the content. Defaults to ElementOverflowBehavior.SCROLL
reference_id (Optional[str], default: '' ) –

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

Input Element Base¶

InputElement ¶

InputElement

Common Patterns¶

Adding Elements to a Page¶

from virtualitics_sdk import Page, Section, Card, Table, PlotlyPlot

page = Page(
    title="My Page",
    sections=[
        Section(
            title="Data Section",
            cards=[
                Card(
                    title="Data Table",
                    content=[
                        Table(data=df)
                    ]
                ),
                Card(
                    title="Visualization",
                    content=[
                        PlotlyPlot(figure=fig)
                    ]
                )
            ]
        )
    ]
)

Getting Input Values¶

def action(self, flow_metadata):
    # Get element by ID
    dropdown = self.page.get_element_by_id("my_dropdown")
    selected_value = dropdown.value

    # Use the value
    filtered_data = data[data['category'] == selected_value]

    return Page(...)

Element IDs¶

Every element should have a unique ID for retrieval:

dropdown = SingleDropdown(
    id="region_selector",  # Unique ID
    title="Select Region",
    options=["North", "South", "East", "West"],
    default="North"
)

# Later, retrieve it
value = self.page.get_element_by_id("region_selector").value

RichText¶

Display formatted text using Markdown:

RichText ¶

RichText(content: str, border: bool = False, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, overflow_behavior: ElementOverflowBehavior = ElementOverflowBehavior.FULLSIZE, reference_id: Optional[str] = '', info_content: Optional[str] = None, on_click: Union[Callback, None] = None)

from virtualitics_sdk import RichText

text = RichText("""
# Welcome

This is **bold** and this is *italic*.

- Bullet point 1
- Bullet point 2

[Link to docs](https://example.com)
""")

RichTextClickable¶

RichTextClickable ¶

Helper class for creating clickable regions within RichText content. Provides static methods to generate clickable HTML elements that trigger RichText callbacks.

from virtualitics_sdk import RichText
from virtualitics_sdk.elements.rich_text import RichTextClickable

# Wrap text in a clickable region
clickable_text = RichTextClickable.wrap("Click here for details", action_id="detail_action")

# Create a button-styled clickable
clickable_btn = RichTextClickable.button("Run Analysis", action_id="run_action")

# Create a link-styled clickable
clickable_link = RichTextClickable.link("View source", action_id="source_action")

# Use inside RichText
rich_text = RichText(
    id="interactive_text",
    content=f"Results are ready. {clickable_text} to explore."
)

See the Button drilldown callback documentation for examples of using RichTextClickable with callbacks.

Image¶

Display images from URLs or base64 data:

Image ¶

Image(content: Image | BytesIO, size: ImageSize = ImageSize.MEDIUM, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, extension: str = 'jpeg', raw_image_bytes: bool = False, overflow_behavior: ElementOverflowBehavior = ElementOverflowBehavior.SCROLL, reference_id: Optional[str] = '', info_content: Optional[str] = None)

from virtualitics_sdk import Image, ImageSize

# From URL
image = Image(
    image_path="https://example.com/image.png",
    size=ImageSize.MEDIUM
)

# From base64
image = Image(
    image_path="data:image/png;base64,iVBORw0KG...",
    size=ImageSize.LARGE
)

Infographic¶

Display key metrics and statistics:

Infographic ¶

Infographic(title: str = '', description: str = '', data: Optional[List[InfographData]] = None, recommendation: Optional[List[InfographData]] = None, layout: InfographicOrientation = InfographicOrientation.ROW, show_title: bool = True, show_description: bool = True, event: Optional[Button] = None, reference_id: Optional[str] = '', overflow_behavior: Optional[ElementOverflowBehavior] = ElementOverflowBehavior.SCROLL, info_content: Optional[str] = None)

from virtualitics_sdk import (
    Infographic,
    InfographData,
    InfographDataType,
    InfographicOrientation
)

infographic = Infographic(
    id="metrics",
    title="Key Metrics",
    data=[
        InfographData(
            label="Total Sales",
            value="$1.2M",
            type=InfographDataType.CURRENCY
        ),
        InfographData(
            label="Growth",
            value="+15%",
            type=InfographDataType.PERCENTAGE
        )
    ],
    orientation=InfographicOrientation.HORIZONTAL
)

DataSource¶

Reference external data connections:

DataSource ¶

DataSource(title: str = '', options: Optional[List[str]] = None, value: str = '', description: str = '', show_title: bool = True, show_description: bool = True, required: bool = True, label: str = '', placeholder: str = '', on_upload_completion: Optional[PageUpdateCallback] = None, on_cancel: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '', downloadable: bool = False, raw_upload: bool = False)

from virtualitics_sdk import DataSource

data_source = DataSource(
    id="my_datasource",
    title="Select Database",
    connection_type="postgresql"
)

Element Overflow Behavior¶

Control how elements handle content that exceeds their container size:

ElementOverflowBehavior ¶

from virtualitics_sdk import RichText, Image, ElementOverflowBehavior

# SCROLL - Add scrollbars when content overflows (default for Image)
scrollable_image = Image(
    content=large_image,
    overflow_behavior=ElementOverflowBehavior.SCROLL
)

# FIT - Scale content to fit within the container
fitted_image = Image(
    content=large_image,
    overflow_behavior=ElementOverflowBehavior.FIT
)

# FULLSIZE - Display content at full size, may extend beyond container (default for RichText)
fullsize_text = RichText(
    content="# Long content...",
    overflow_behavior=ElementOverflowBehavior.FULLSIZE
)

Overflow Behavior Options:

SCROLL: Adds scrollbars when content is larger than the container. Best for images and content that should maintain its original size.
FIT: Automatically scales content to fit within the container boundaries. Useful for responsive images.
FULLSIZE: Displays content at its natural size, potentially extending beyond the container. Best for text content that should flow naturally.

Best Practices¶

Use Unique IDs: Every element needs a unique ID for retrieval
Appropriate Element Types: Choose the right element for your data
Clear Labels: Use descriptive titles and labels
Default Values: Provide sensible defaults for input elements
Validation: Validate user inputs in action() method
Performance: Large tables/plots may impact performance