Dropdowns¶

Dropdown elements allow users to select one or more options from a list.

SingleDropdown¶

Select one option from a list:

Dropdown ¶

Dropdown(options: List[str | int | float] | Dict[str, str | int | float], selected: Optional[List[str | int | float]] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, multiselect: bool = False, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, required: bool = True, label: str = '', placeholder: str = '', max_selections: Optional[int] = None, page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')

A Dropdown Input element.

Parameters:

options (List[str | int | float] | Dict[str, str | int | float]) –

The options in the dropdown menu.
selected (Optional[List[str | int | float]], default: None ) –

The option the user selected, defaults to [].
include_nulls_visible (bool, default: True ) –

whether null values will be visible, defaults to True.
include_nulls_value (bool, default: False ) –

whether to include null values, defaults to False.
multiselect (bool, default: False ) –

whether the user can select multiple values, defaults to False.
title (str, default: '' ) –

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

The element's description, 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.
required (bool, default: True ) –

whether a selection needs to be submitted for the step to continue, defaults to True
label (str, default: '' ) –

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

The placeholder of the element, defaults to ''.
max_selections (Optional[int], default: None ) –

The maximum number of selections that can be made at one time, no limit set by default. This value must be greater than zero.
page_update (Optional[PageUpdateCallback], default: None ) –

Updater function. Allows for handling dynamic page update on a page Takes a StoreInterface and optionally client runners as arguments, defaults to None.
reference_id (Optional[str], default: '' ) –

A user-defined reference ID for the unique identification of Dropdown element within the Page, defaults to ''. EXAMPLE .. code-block:: python # Imports from virtualitics_sdk import Dropdown . . . # Example usage class ExStep(Step): def run(self, flow_metadata): . . . dropdown_options = ['a', 'b', 'c'] single_selection_dropdown = Dropdown(options=dropdown_options, multiselect=False, title="Single Selection Dropdown", selected=['a']) multiple_selection_dropdown = Dropdown(options=dropdown_options, multiselect=True, title="Multiple Selection Dropdown", selected=['a', 'b']) The above single and multi Dropdown examples will be displayed as: .. image:: ../images/dropdown_ex.png :align: center How to use page_update .. code-block:: python # Imports from virtualitics_sdk import Dropdown . . . . . . # Example page update function def updater(store_interface: StoreInterface): current_page = store_interface.get_page() updated_example_element = modify(example_element) # modify element(s) in the card current_page.replace_content_in_section( elems=[updated_example_element], section_title="Ex Section", card_title="Example Card" ) store_interface.update_page(current_page) # Example usage of page updater class ExStep(Step): def run(self, flow_metadata): store_interface = StoreInterface(**flow_metadata) page = store_interface.get_page() . . . dropdown_element = Dropdown( ["yes", "no"], label="Answer", title="updatable", placeholder="Select One", page_update=updater ) card = Card(title="Example Card", content=[dropdown_element, example_element], page.add_card_to_section(card, "Ex Section")

from virtualitics_sdk import SingleDropdown

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

MultiDropdown¶

Select multiple options from a list:

Dropdown ¶

Dropdown(options: List[str | int | float] | Dict[str, str | int | float], selected: Optional[List[str | int | float]] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, multiselect: bool = False, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, required: bool = True, label: str = '', placeholder: str = '', max_selections: Optional[int] = None, page_update: Optional[PageUpdateCallback] = None, reference_id: Optional[str] = '')

A Dropdown Input element.

Parameters:

options (List[str | int | float] | Dict[str, str | int | float]) –

The options in the dropdown menu.
selected (Optional[List[str | int | float]], default: None ) –

The option the user selected, defaults to [].
include_nulls_visible (bool, default: True ) –

whether null values will be visible, defaults to True.
include_nulls_value (bool, default: False ) –

whether to include null values, defaults to False.
multiselect (bool, default: False ) –

whether the user can select multiple values, defaults to False.
title (str, default: '' ) –

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

The element's description, 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.
required (bool, default: True ) –

whether a selection needs to be submitted for the step to continue, defaults to True
label (str, default: '' ) –

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

The placeholder of the element, defaults to ''.
max_selections (Optional[int], default: None ) –

The maximum number of selections that can be made at one time, no limit set by default. This value must be greater than zero.
page_update (Optional[PageUpdateCallback], default: None ) –

Updater function. Allows for handling dynamic page update on a page Takes a StoreInterface and optionally client runners as arguments, defaults to None.
reference_id (Optional[str], default: '' ) –

A user-defined reference ID for the unique identification of Dropdown element within the Page, defaults to ''. EXAMPLE .. code-block:: python # Imports from virtualitics_sdk import Dropdown . . . # Example usage class ExStep(Step): def run(self, flow_metadata): . . . dropdown_options = ['a', 'b', 'c'] single_selection_dropdown = Dropdown(options=dropdown_options, multiselect=False, title="Single Selection Dropdown", selected=['a']) multiple_selection_dropdown = Dropdown(options=dropdown_options, multiselect=True, title="Multiple Selection Dropdown", selected=['a', 'b']) The above single and multi Dropdown examples will be displayed as: .. image:: ../images/dropdown_ex.png :align: center How to use page_update .. code-block:: python # Imports from virtualitics_sdk import Dropdown . . . . . . # Example page update function def updater(store_interface: StoreInterface): current_page = store_interface.get_page() updated_example_element = modify(example_element) # modify element(s) in the card current_page.replace_content_in_section( elems=[updated_example_element], section_title="Ex Section", card_title="Example Card" ) store_interface.update_page(current_page) # Example usage of page updater class ExStep(Step): def run(self, flow_metadata): store_interface = StoreInterface(**flow_metadata) page = store_interface.get_page() . . . dropdown_element = Dropdown( ["yes", "no"], label="Answer", title="updatable", placeholder="Select One", page_update=updater ) card = Card(title="Example Card", content=[dropdown_element, example_element], page.add_card_to_section(card, "Ex Section")

from virtualitics_sdk import MultiDropdown

dropdown = MultiDropdown(
    id="feature_selector",
    title="Select Features",
    options=["Feature A", "Feature B", "Feature C", "Feature D"],
    default=["Feature A", "Feature B"]
)

Getting Selected Values¶

In your step's action() method:

def action(self, flow_metadata):
    # Single selection
    selected_region = self.page.get_element_by_id("region_selector").value
    # selected_region is a string, e.g., "North"

    # Multiple selection
    selected_features = self.page.get_element_by_id("feature_selector").value
    # selected_features is a list, e.g., ["Feature A", "Feature B"]

    # Use selections to filter data
    filtered_data = self._inLink.data[
        self._inLink.data['region'] == selected_region
    ]

    return Page(...)

Dynamic Options¶

Update dropdown options based on data:

def run(self, flow_metadata):
    # Get unique values from data
    df = self._inLink.dataset.data
    unique_categories = sorted(df['category'].unique().tolist())

    dropdown = SingleDropdown(
        id="category_filter",
        title="Select Category",
        options=unique_categories,
        default=unique_categories[0] if unique_categories else None
    )

    return Page(
        title="Filter Data",
        sections=[
            Section(
                title="Filters",
                cards=[Card(title="Category", content=[dropdown])]
            )
        ]
    )

Select from external data connections:

DataSourceDropdown ¶

DataSourceDropdown(user_id: str, options: List[ConnectionType], selected: Optional[List[str]] = None, include_nulls_visible: bool = True, include_nulls_value: bool = False, title: str = '', description: str = '', show_title: bool = True, show_description: bool = True, required: bool = True, label: str = '', placeholder: str = '')

Used to configure data source drop down options that have been set up in the Connections tab.

Parameters:

user_id (str) –

the user_id of the owner of the connections, usually done via StoreInterface.user.
options (List[ConnectionType]) –

a list of ConnectionTypes, for example ConnectionType.mssql.
selected (Optional[List[str]], default: None ) –

used if you want a default selection.
include_nulls_visible (bool, default: True ) –

whether null values will be visible.
include_nulls_value (bool, default: False ) –

whether to include null values.
title (str, default: '' ) –

the title of the drop-down element.
description (str, default: '' ) –

the description of the drop-down element.
show_title (bool, default: True ) –

whether to show the title.
show_description (bool, default: True ) –

whether to show the description.
required (bool, default: True ) –

whether selecting an item from the dropdown is required to proceed.
label (str, default: '' ) –

the label of the element.

placeholder (str, default: '' ) –

EXAMPLE:

# Imports  from virtualitics_sdk import DataSourceDropdown...
# Example usage class ExampleStep(Step): def run(self, flow_metadata):...
api_key_selection = DataSourceDropdown(user_id=store_interface.user, options=[ConnectionType.s3, ConnectionType.other], title='Select API Credential')  The above DataSourceDropdown example will be displayed as:   .. image:: ../images/dropdown_data_ex.png :align: center

from virtualitics_sdk import DataSourceDropdown

datasource_dropdown = DataSourceDropdown(
    id="db_selector",
    title="Select Database Connection",
    connection_types=["postgresql", "mysql", "snowflake"]
)

Cascading Dropdowns¶

Create dependent dropdowns:

class FilterStep(Step):
    def run(self, flow_metadata):
        df = self._inLink.data

        # First dropdown - select category
        categories = sorted(df['category'].unique().tolist())
        category_dropdown = SingleDropdown(
            id="category",
            title="Select Category",
            options=categories,
            default=categories[0]
        )

        return Page(
            title="Filters",
            sections=[
                Section(
                    title="Select Options",
                    cards=[Card(title="Category", content=[category_dropdown])]
                )
            ]
        )

    def action(self, flow_metadata):
        df = self._inLink.data
        selected_category = self.page.get_element_by_id("category").value

        # Filter subcategories based on category
        filtered_df = df[df['category'] == selected_category]
        subcategories = sorted(filtered_df['subcategory'].unique().tolist())

        # Second dropdown - select subcategory
        subcategory_dropdown = SingleDropdown(
            id="subcategory",
            title="Select Subcategory",
            options=subcategories,
            default=subcategories[0] if subcategories else None
        )

        category_dropdown = SingleDropdown(
            id="category",
            title="Select Category",
            options=sorted(df['category'].unique().tolist()),
            default=selected_category
        )

        return Page(
            title="Filters",
            sections=[
                Section(
                    title="Select Options",
                    cards=[
                        Card(
                            title="Filters",
                            content=[category_dropdown, subcategory_dropdown]
                        )
                    ]
                )
            ]
        )

Best Practices¶

Unique IDs: Each dropdown needs a unique ID
Default Values: Always provide a sensible default
Sorted Options: Sort options alphabetically for user convenience
Null Handling: Handle cases where options list might be empty
Clear Labels: Use descriptive titles that explain what to select
Limit Options: Very long lists (>100 items) may need alternative UI

Dropdowns¶

Dropdown Classes¶

SingleDropdown¶

Dropdown ¶

MultiDropdown¶

Dropdown ¶

Getting Selected Values¶

Dynamic Options¶

Data Source Dropdown¶

DataSourceDropdown ¶

Cascading Dropdowns¶

Best Practices¶

See Also¶