Fields¶
These are the fields supported by MicroApps. They are a subset of fields that are supported by Streamlit and use much of the same syntax.
text_input¶
Display a single-line text input widget.
Parameters
| type ("default" or "password") | The type of the text input. This can be either "default" (for a regular text input), or "password" (for a text input that masks the user's typed value). Defaults to "default". |
| label (str) | A short label explaining to the user what this input is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| value (object or None) | The text value of this widget when it first renders. This will be cast to str internally. If None, will initialize empty and return None until the user provides input. Defaults to empty string. |
| max_chars (int or None) | Max number of characters allowed in text input. |
| help (str) | An optional tooltip that gets displayed next to the input. |
| placeholder (str or None)
[keyword only] |
An optional string displayed when the text input is empty. If None, no text is displayed. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
text_area¶
Display a multi-line text input widget.
Parameters
| label (str) | A short label explaining to the user what this input is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| value (object or None) | The text value of this widget when it first renders. This will be cast to str internally. If None, will initialize empty and return None until the user provides input. Defaults to empty string. |
| height (int or None) | Desired height of the UI element expressed in pixels. If None, a default height is used. |
| max_chars (int or None) | Maximum number of characters allowed in text area. |
| help (str) | An optional tooltip that gets displayed next to the textarea. |
| placeholder (str or None)
[keyword only] |
An optional string displayed when the text area is empty. If None, no text is displayed. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
chat_input¶
The chat_input field is a chatbot like multi-turn input field where the user can have a conversation with the AI assistant. This field is especially useful in applications where ongoing dialogue is important, and/or the number of turns in the conversation is unknown.
Parameters:
| max_messages (int or None) | This optional parameter sets the maximum number of messages that can be sent and received in the conversation. In this case, a "message" is defined as a turn in the conversation with a user input and a response from the assistant. (So, "Hi Assistant", "Hi John", "Goodbye Assistant", "Goodbye John" would be 2 messages). If left unset, the default maximum is 50 messages. |
| initial_assistant_message (str) | This optional parameter specifies the initial message that the AI assistant will display to the user at the start of the conversation. This helps set the context for users when they first engage with the chat. |
| placeholder (str) | This optional parameter sets the placeholder text that will be displayed in the input field when the user has not yet sent a message. This helps guide users on what to input. |
warning¶
Display warning message.
| body (str) | The warning text to display. |
button¶
Display a button widget.
Parameters:
| label (str) | A short label explaining to the user what this button is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. |
| help (str) | An optional tooltip that gets displayed when the button is hovered over. |
| on_click (callable) | An optional callback invoked when this button is clicked. |
| type ("secondary" or "primary")
[keyword only] |
An optional string that specifies the button type. Can be "primary" for a button with additional emphasis or "secondary" for a normal button. Defaults to "secondary". |
Radio¶
Display a radio button widget.
Parameters:
| label (str) | A short label explaining to the user what this radio group is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| options (Iterable) | Labels for the select options in an Iterable. This can be a list, set, or anything supported by st.dataframe. If options is dataframe-like, the first column will be used. Each label will be cast to str internally by default.
Labels can include markdown as described in the label parameter and will be cast to str internally by default. |
| index (int or None) | The index of the preselected option on first render. If None, will initialize empty and return None until the user selects an option. Defaults to 0 (the first option). |
| help (str) | An optional tooltip that gets displayed next to the radio. |
| horizontal (bool)
[keyword only] |
An optional boolean, which orients the radio group horizontally. The default is false (vertical buttons). |
| captions (iterable of str or None)
[keyword only] |
A list of captions to show below each radio button. If None (default), no captions are shown. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
markdown¶
Display string formatted as Markdown.
Parameters:
| body (str) | The string to display as GitHub-flavored Markdown. Syntax information can be found at: https://github.github.com/gfm
This also supports:
|
| unsafe_allow_html (bool) | Whether to render HTML within body. If this is False (default), any HTML tags found in body will be escaped and therefore treated as raw text. If this is True, any HTML expressions within body will be rendered.
Adding custom HTML to your app impacts safety, styling, and maintainability. Note: If you only want to insert HTML or CSS without Markdown text, we recommend using st.html instead. |
| help (str)
[keyword only] |
An optional tooltip that gets displayed next to the Markdown. |
selectbox¶
Display a select widget.
Parameters:
| label (str) | A short label explaining to the user what this select widget is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| options (Iterable) | Labels for the select options in an Iterable. This can be a list, set, or anything supported by st.dataframe. If options is dataframe-like, the first column will be used. Each label will be cast to str internally by default. |
| index (int) | The index of the preselected option on first render. If None, will initialize empty and return None until the user selects an option. Defaults to 0 (the first option). |
| help (str) | An optional tooltip that gets displayed next to the selectbox. |
| placeholder (str)
[keyword only] |
A string to display when no options are selected. Defaults to "Choose an option". |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
checkbox¶
Display a checkbox widget.
Parameters:
| label (str) | A short label explaining to the user what this checkbox is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| value (bool) | Preselect the checkbox when it first renders. This will be cast to bool internally. |
| help (str) | An optional tooltip that gets displayed next to the checkbox. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
Slider¶
Display a slider widget.
This supports int, float, date, time, and datetime types.
This also allows you to render a range slider by passing a two-element tuple or list as the value.
Note: Integer values exceeding +/- (1<<53) - 1 cannot be accurately stored or returned by the widget due to serialization constraints between the Python server and JavaScript client. You must handle such numbers as floats, leading to a loss in precision.
Parameters:
| label (str) | A short label explaining to the user what this slider is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| min_value (a supported type or None) | The minimum permitted value. Defaults to 0 if the value is an int, 0.0 if a float, value - timedelta(days=14) if a date/datetime, time.min if a time. |
| max_value (a supported type or None) | The maximum permitted value. Defaults to 100 if the value is an int, 1.0 if a float, value + timedelta(days=14) if a date/datetime, time.max if a time. |
| value (a supported type or a tuple/list of supported types or None) | The value of the slider when it first renders. If a tuple/list of two values is passed here, then a range slider with those lower and upper bounds is rendered. For example, if set to (1, 10) the slider will have a selectable range between 1 and 10. Defaults to min_value. |
| step (int, float, timedelta, or None) | The stepping interval. Defaults to 1 if the value is an int, 0.01 if a float, timedelta(days=1) if a date/datetime, timedelta(minutes=15) if a time (or if max_value - min_value < 1 day) |
| help (str) | An optional tooltip that gets displayed next to the slider. |
| label_visibility ("visible", "hidden", or "collapsed") | The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
number_input¶
Display a numeric input widget.
Note: Integer values exceeding +/- (1<<53) - 1 cannot be accurately stored or returned by the widget due to serialization contstraints between the Python server and JavaScript client. You must handle such numbers as floats, leading to a loss in precision.
Parameters:
| label (str) | A short label explaining to the user what this input is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| min_value (int, float, or None) | The minimum permitted value. If None, there will be no minimum. |
| max_value (int, float, or None) | The maximum permitted value. If None, there will be no maximum. |
| value (int, float, "min" or None) | The value of this widget when it first renders. If None, will initialize empty and return None until the user provides input. If "min" (default), will initialize with min_value, or 0.0 if min_value is None. |
| step (int, float, or None) | The stepping interval. Defaults to 1 if the value is an int, 0.01 otherwise. If the value is not specified, the format parameter will be used. |
| help (str) | An optional tooltip that gets displayed next to the input. |
| placeholder (str or None)
[keyword only] |
An optional string displayed when the number input is empty. If None, no placeholder is displayed. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
Image¶
Display an image with optional caption.
Parameters:
| image (numpy.ndarray, [numpy.ndarray], BytesIO, str, or [str]) | Monochrome image of shape (w,h) or (w,h,1) OR a color image of shape (w,h,3) OR an RGBA image of shape (w,h,4) OR a URL to fetch the image from OR a path of a local image file OR an SVG XML string like <svg xmlns=...</svg> OR a list of one of the above, to display multiple images. |
| caption (str or list of str) | Image caption. If displaying multiple images, caption should be a list of captions (one for each image). |
file_uploader¶
Display a file uploader widget.
By default, uploaded files are limited to 200MB. You can configure this using the server.maxUploadSize config option. For more info on how to set config options, see https://docs.streamlit.io/develop/api-reference/configuration/config.toml
Parameters:
| label (str) | A short label explaining to the user what this file uploader is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links.
Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
| type (str or list of str or None) | Array of allowed extensions. ['png', 'jpg'] The default is None, which means all extensions are allowed. |
| help (str) | A tooltip that gets displayed next to the file uploader. |
| label_visibility ("visible", "hidden", or "collapsed")
[keyword only] |
The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
Conditional Fields¶
Fields can be shown or hidden based on conditional logic.
Let's look at an example. Let's say we want to ask our user to choose their favorite character from a book, and then ask them a question about that character. We only want to show the second question after they've answered the first.
This is our configuration:
PHASES = {
"phase1": {
"name": "Tell me about a character in Canterbury Tales",
"fields": {
"character": {
"type": "radio",
"label": "Choose your favorite character",
"options": ['The Knight', 'The Monk', 'The Pardoner']
},
"represent": {
"type": "text_area",
"label": "What does this character represent in the book?",
"showIf": {"character": {"$ne": ""}}
}
},
"show_prompt": True,
"user_prompt": "My favorite character from Canterbury Tales is {character} and this is what they represent in the book: {represent}. Provide feedback on my analysis. "
},
}
And this is the rendered app before the user has met the conditional (answered the first question):
And here is the app again after the user has met the conditional (they answered the first question), so the second question appears.
Boolean Conditionals¶
Boolean values can be conditional based on whether they are True or False. If the condition is met, then the prompt snippet is included.
Boolean conditionals can be:
- True
- False
Code Sample
"fields": {
"read": {
"type": "checkbox",
"label": "Have you read the book?",
},
"represent": {
"type": "text_area",
"label": "Provide a two paragraph summary of the book.",
"showIf": {"read": True}
}
Numeric Conditionals¶
Numeric values can be conditional based on numbers that you choose. If the condition is met, then the prompt snippet is included.
Numeric conditionals can be:
- equal to
- greater than (
$gt) - less than (
$lt) - greater than or equal to (
$gte) - less than or equal to (
$lte) - not equal to (
$ne)
Code Sample
"fields": {
"age": {
"type": "number_input",
"label": "What is your age?",
},
"license": {
"type": "checkbox",
"label": "Do you have a valid driver's license?",
"showIf": {"age": {"$gte": 16}}
}
String Conditionals¶
String values can be conditional based on if they match a string that you choose. If the condition is met, then the prompt snippet is included.
String conditionals can be:
- equal to
- not equal to (
$ne)
Code Sample
"fields": {
"education": {
"type": "radio",
"label": "What is your education level?",
"options": ['High School or Less','Some College Education']
},
"higher_education": {
"type": "radio",
"label": "What is your highest degree achieved?",
"options": ['None','Associates','Bachelor','Masters or PhD'],
"showIf": {"education": "Some College Education"}
}
List Conditionals¶
Lists can be conditional based on whether they contain or do not contain certain values. If the condition is met, then the prompt snippet is included.
- in (
$in) - not in (
$nin)
Code Sample
Note: AI MicroApps don't support any fields that return lists at the moment. Therefore, there are no code samples and this is a placeholder for when we do support list input fields.
Logic (and/or) Conditionals¶
Conditionals can be combined with and, or, and not
- and (
$and) - or (
$or)
Code Sample
"fields": {
"age": {
"type": "number_input",
"label": "What is your age?",
},
"license": {
"type": "checkbox",
"label": "Do you have a valid driver's license?",
"showIf": {"age": {"$gte": 16}}
},
"driver": {
"type": "radio",
"label": "Can you get a parent or guardian to drive you when you need it?",
"options": ['yes','no'],
"showIf": {
"$or": [
{"age": {"$lt": 16}},
{"license": False}
]
}
}