# st.chat_input

Source: https://docs.streamlit.io/develop/api-reference/chat/st.chat_input

> **Tip**
>
> Read the [Build a basic LLM chat app](https://docs.streamlit.io/develop/tutorials/chat-and-llm-apps/build-conversational-apps) tutorial to learn how to use `st.chat_message` and `st.chat_input` to build chat-based apps.

* Function signature:

   ```python
   st.chat_input(placeholder="Your message", *, key=None, max_chars=None, max_upload_size=None, accept_file=False, file_type=None, accept_audio=False, audio_sample_rate=16000, disabled=False, submit_mode="submit", on_submit=None, args=None, kwargs=None, width="stretch", height="content")
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | placeholder | str |  | A placeholder text shown when the chat input is empty. This defaults to "Your message". For accessibility reasons, you should not use an empty string. |
   | key | str, int, or None |  | An optional string or integer to use as the unique key for the widget. If this is None (default), a key will be generated for the widget based on the values of the other parameters. No two widgets may have the same key. Assigning a key stabilizes the widget's identity and preserves its state across reruns even when other parameters change.  Note Changing accept_file, file_type, max_chars, or max_upload_size resets the widget even when a key is provided.  A key lets you read or update the widget's value via st.session_state[key]. For more details, see Widget behavior. Additionally, if key is provided, it will be used as a CSS class name prefixed with st-key-. |
   | max_chars | int or None |  | The maximum number of characters that can be entered. If this is None (default), there will be no maximum. |
   | max_upload_size | int or None |  | The maximum allowed size of each uploaded file in megabytes. If this is None (default), the maximum file size is set by the server.maxUploadSize configuration option in your config.toml file. If this is an integer, it must be positive and will override the server.maxUploadSize configuration option. |
   | accept_file | bool, "multiple", or "directory" |  | Whether the chat input should accept files. This can be one of the following values:  False (default): No files are accepted and the user can only submit a message. True: The user can add a single file to their submission. "multiple": The user can add multiple files to their submission. "directory": The user can add multiple files to their submission by selecting a directory. If file_type is set, only files matching those type(s) will be uploaded.  By default, uploaded files are limited to 200 MB each. You can configure this using the server.maxUploadSize config option. For more information on how to set config options, see config.toml. |
   | file_type | str, Sequence[str], or None |  | The allowed file types for uploaded files. This can be one of the following values:  None (default): All file extensions are allowed. A file extension: Only one file extension is allowed. For example, to only accept CSV files, use "csv" or ".csv". A MIME type: Only one MIME type is allowed. For example, to accept JPEG images, use "image/jpeg". A MIME wildcard: All types within a MIME media type are allowed. For example, to accept all images, use "image/*". A MIME media type: This is a shortcut that is equivalent to a MIME wildcard. If you use "image", "audio", "video", or "text", Streamlit will internally append /* to create a MIME wildcard. A sequence of strings: Use a combination of the previously listed strings to accept multiple file types.  For more information about MIME types, see https://www.iana.org/assignments/media-types/media-types.xhtml.  Note This is a best-effort check, but doesn't provide a security guarantee against users uploading files of other types or type extensions. The correct handling of uploaded files is part of the app developer's responsibility. |
   | accept_audio | bool |  | Whether to show an audio recording button in the chat input. This defaults to False. If this is True, users can record and submit audio messages. Recorded audio is available as an UploadedFile object with MIME type audio/wav. |
   | audio_sample_rate | int or None | sample | The target sample rate for audio recording in Hz when accept_audio is True. This defaults to 16000, which is optimal for speech recognition. The following values are supported: 8000 (telephone quality), 11025, 16000 (speech-recognition quality), 22050, 24000, 32000, 44100, 48000 (high-quality), or None. If this is None, the widget uses the browser's default sample rate (typically 44100 or 48000 Hz). |
   | disabled | bool |  | Whether the chat input should be disabled. This defaults to False. |
   | submit_mode | "submit", "disable", or "stop" |  | Controls widget behavior after the user submits a message while the script is running. This can be one of the following values:  "submit" (default): The widget remains fully enabled after submission. Users can submit new messages while the script is running. "disable": The widget is automatically disabled after the user submits a message and re-enables when the script run completes. This prevents users from interrupting ongoing operations like LLM streaming. "stop": The submit button transforms into a stop button after submission. Clicking it stops the script execution, similar to clicking "Stop" in the app's status widget. The text area is disabled while the script runs. |
   | on_submit | callable |  | An optional callback invoked when the chat input's value is submitted. |
   | args | list or tuple |  | An optional list or tuple of args to pass to the callback. |
   | kwargs | dict |  | An optional dict of kwargs to pass to the callback. |
   | width | "stretch" or int |  | The width of the chat input widget. This can be one of the following:  "stretch" (default): The width of the widget matches the width of the parent container. An integer specifying the width in pixels: The widget has a fixed width. If the specified width is greater than the width of the parent container, the width of the widget matches the width of the parent container. |
   | height | "content", "stretch", or int | single-line | The minimum height of the chat input widget. This can be one of the following:  "content" (default): The widget uses the default single-line height and automatically expands based on the text content. "stretch": The height of the widget stretches to fill the available height of the parent container. The parent container must have a defined height for this to work properly. An integer specifying the minimum height in pixels: The widget has a fixed minimum height but still auto-expands based on text content. The minimum recommended height is 68 pixels, which fits a single line of text. |

* Returns: None, str, or ChatInputValue

    The user's submission. This is one of the following types:

None: If the user didn't submit a message, file, or audio
recording in the last rerun, the widget returns None.
A string: When the widget isn't configured to accept files or
audio recordings, and the user submitted a message in the last
rerun, the widget returns the user's message as a string.
A ChatInputValue object: When the widget is configured to
accept files or audio recordings, and the user submitted any
content in the last rerun, the widget returns a ChatInputValue
object. This object is dictionary-like and supports both key and
attribute notation.
The object always includes the text attribute, and
optionally includes files and/or audio attributes depending
on the accept_file and accept_audio parameters.

To use ChatInputValue or UploadedFile in an annotation,
import them from streamlit.typing.
When the widget is configured to accept files or audio recordings,
and the user submitted content in the last rerun, you can access
the user's submission with key or attribute notation from the
dict-like object. This is shown in Example 3 below.

The text attribute holds a string that is the user's message.
This is an empty string if the user only submitted one or more
files or audio recordings.
The files attribute is only present when accept_file
isn't False. When present, it holds a list of
UploadedFile objects. The list is empty if the user only
submitted a message or audio recording. Unlike
st.file_uploader, this attribute always returns a list, even
when the widget is configured to accept only one file at a time.
The audio attribute is only present when accept_audio is
True. When present, it holds an UploadedFile object if
audio was recorded or None if no audio was recorded.

The UploadedFile class is a subclass of BytesIO and
therefore is "file-like". This means you can pass an instance of it
anywhere a file is expected.

* Function signature:

   ```python
   ChatInputValue
   ```

* Parameters:

   | name | type | default | description |
   |---|---|---|---|
   | text | str |  | The text input provided by the user. |
   | files | list[UploadedFile] |  | A list of files uploaded by the user. Only present when accept_file=True. |
   | audio | UploadedFile or None |  | An audio recording uploaded by the user, if any. Only present when accept_audio=True. |

For an overview of the `st.chat_input` and `st.chat_message` API, check out this video tutorial by Chanin Nantasenamat ([@dataprofessor](https://www.youtube.com/dataprofessor)), a Senior Developer Advocate at Streamlit.

[Watch on YouTube](https://www.youtube.com/watch?v=4sPnOqeUDmk)
