1. Contents
  2. ComponentArgs
  3. setStateValue
  4. setTriggerValue

ComponentArgs

The arguments passed to a Streamlit custom component's top-level export default function.

import { ComponentArgs } from '@streamlit/component-v2-lib';

This type provides the interface between your TypeScript component and Streamlit's runtime, including the data payload from Python, utilities for managing component state, and the DOM container for mounting your UI.

Component authors typically destructure these arguments for easier access.

(TypeScript) Type alias description[source]

ComponentArgs<TComponentState = ComponentState, TDataShape = unknown,>

Functions

setStateValue(name, value)

Set a state value by key. This state persists across app reruns. State values are accessible in Python through the component's result. Use this for values that should maintain their state when the user interacts with other parts of the Streamlit app.

setTriggerValue(name, value)

Set a trigger value by key. This trigger persists for a only single app rerun.

Trigger values are one-time events that are consumed during the resulting rerun and reset to null afterward. They're accessible in Python through the component's result. Use this for actions like button clicks, form submissions, or other event-based interactions.

Properties

data (TDataShape)

The data payload sent from Python through the component's mounting command. This is the primary input for your component, typed by the component author via the TDataShape generic.

key (string)

A stable identifier for this component instance generated by Streamlit. This key is independent from the key parameter passed to the component's mounting command in Python. This frontend key is automatically generated to be unique among all instances of all components and to avoid collisions with classes and IDs in the app's DOM.

Important

If a component is mounted without a key parameter in Python, and one of the parameters in the mounting command changes, then this frontend key may change between app runs.

name (string)

The component's name, as registered by Streamlit on the Python side. This is the same as the name parameter passed to st.components.v2.component.

parentElement (HTMLElement or ShadowRoot)

The host element for your component. Your HTML, JavaScript, and CSS are mounted inside this container. This is a ShadowRoot if isolate_styles is set to true in the component definition, otherwise it's an HTMLElement.

Example

Defining strict typing is not required. However, to follow typing best practices, you can declare your component's data and state shapes, then provide them as generic parameters to ComponentArgs. The following TypeScript code must be compiled to JavaScript before being passed to the component's js parameter in st.components.v2.component.

import { Component, ComponentState } from '@streamlit/component-v2-lib';

interface MyComponentState extends ComponentState {
    selected_item: string | null
    button_clicked: boolean
}

interface MyComponentData {
    label: string
    options: string[]
}

const MyComponent: Component<MyComponentState, MyComponentData> = (component) => {
    // Destructure the component args for easier access
    const { data, setStateValue, setTriggerValue, parentElement } = component

    // Set up event handlers with type-safe state management
    const dropdown = parentElement.querySelector('#dropdown') as HTMLSelectElement
    const button = parentElement.querySelector('#submit') as HTMLButtonElement

    dropdown.onchange = () => {
        setStateValue('selected_item', dropdown.value)
    }

    button.onclick = () => {
        setTriggerValue('button_clicked', true)
    }
}

export default MyComponent;

setStateValue

Set a state value by key. This state persists across app reruns. State values are accessible in Python through the component's result. Use this for values that should maintain their state when the user interacts with other parts of the Streamlit app.

Function signature[source]

setStateValue(name, value)

Parameters

name (string)

The state key to set. If you are using TypeScript, this should be a key from TComponentState.

To assign a value to a state key, in the component's mounting command in Python, an on_<key>_change callback isn't required. However, the presence of a callback will ensure that the state key is always present in the result.

value (Any)

The value to associate with the key. Type must match the corresponding property type in your TComponentState interface.

Returns

(None)

No description

setTriggerValue

Set a trigger value by key. This trigger persists for a only single app rerun.

Trigger values are one-time events that are consumed during the resulting rerun and reset to null afterward. They're accessible in Python through the component's result. Use this for actions like button clicks, form submissions, or other event-based interactions.

Function signature[source]

setTriggerValue(name, value)

Parameters

name (string)

The trigger key to set. If you are using TypeScript, this should be a key from TComponentState.

To assign a value to a trigger key, in the component's mounting command in Python, an on_<key>_change callback isn't required. However, the presence of a callback will ensure that the trigger key is always present in the result.

value (Any)

The value for this trigger. If you are using TypeScript, this should match the corresponding property type in your TComponentState interface.

Returns

(None)

No description

arrow_backPrevious: Componentarrow_forwardNext: ComponentState
forum

Still have questions?

Our forums are full of helpful information and Streamlit experts.