{"id":6256,"library":"streamlit-option-menu","title":"Streamlit Option Menu","description":"streamlit-option-menu is a simple Streamlit component that allows users to select a single item from a list of options in a menu. It provides a static list of options with configurable icons and extensive CSS styling capabilities, offering an alternative to `st.selectbox()` for navigation. The current stable version is 0.4.0, with regular updates and community engagement.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/victoryhb/streamlit-option-menu","tags":["streamlit","component","menu","navigation","ui","sidebar"],"install":[{"cmd":"pip install streamlit-option-menu","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for any Streamlit custom component.","package":"streamlit","optional":false}],"imports":[{"symbol":"option_menu","correct":"from streamlit_option_menu import option_menu"}],"quickstart":{"code":"import streamlit as st\nfrom streamlit_option_menu import option_menu\n\nst.set_page_config(layout=\"wide\")\n\nwith st.sidebar:\n    selected = option_menu(\n        menu_title=\"Main Menu\",  # required\n        options=[\"Home\", \"Projects\", \"Contact\"],  # required\n        icons=[\"house\", \"code-slash\", \"envelope\"],  # optional\n        menu_icon=\"cast\",  # optional\n        default_index=0,  # optional\n        orientation=\"vertical\"\n    )\n\nif selected == \"Home\":\n    st.title(f\"You selected: {selected}\")\n    st.write(\"Welcome to the Home page!\")\nelif selected == \"Projects\":\n    st.title(f\"You selected: {selected}\")\n    st.write(\"Here are my projects.\")\nelif selected == \"Contact\":\n    st.title(f\"You selected: {selected}\")\n    st.write(\"Contact me here.\")","lang":"python","description":"This example demonstrates how to create a vertical navigation menu in the sidebar using `streamlit-option-menu`, displaying different content based on the user's selection."},"warnings":[{"fix":"Store and retrieve the selected value using `st.session_state` and explicitly pass it as `default_index` if the menu is re-rendered conditionally or after query parameter changes. This ensures the UI state aligns with the session state. Avoid relying solely on query parameters for menu state if UI desynchronization is observed.","message":"The `option_menu` UI may incorrectly refresh to its default state after `st.experimental_set_query_params` is called, even if the underlying selected value remains correct. The UI might not visually reflect the intended selection.","severity":"gotcha","affected_versions":"All versions where `st.experimental_set_query_params` is used with `option_menu`."},{"fix":"Ensure you use only one dependency management file (`requirements.txt` is generally recommended for simplicity with Streamlit Cloud) and remove the other. If using `Pipfile`, ensure `streamlit-option_menu` is correctly listed and a `Pipfile.lock` is generated.","message":"When deploying Streamlit applications to platforms like Streamlit Cloud, having both `Pipfile` (and `Pipfile.lock`) and `requirements.txt` in your repository can lead to dependency resolution errors where `streamlit-option-menu` is not found. Streamlit prioritizes which dependency file to use.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always store the selected value in `st.session_state` if the menu's visibility or parameters might change, and use `st.session_state` to set the `default_index` on subsequent renders to maintain the selection state.","message":"Like most Streamlit components, `streamlit-option-menu` triggers a full app rerun when its value changes. If the component is displayed conditionally or hidden, its value might reset on subsequent reruns if not properly managed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test custom CSS thoroughly within the component's `styles` dictionary. Be aware of the iframe isolation and that external CSS or global Streamlit theming might not directly affect the component's internal elements. For deeper customization, understanding Bootstrap CSS (which the component uses) can be beneficial.","message":"Custom CSS applied via the `styles` parameter might not always behave as expected or interact with the main Streamlit app's CSS. This is because custom components are often rendered within an iframe, isolating their styling from the parent document.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `manual_select` only when a manual selection is intended, typically within a conditional block or based on an event. Ensure it is not set persistently on every rerun to allow normal user interaction.","message":"The `manual_select` parameter is designed for one-time programmatic selection and behaves like a button. If `manual_select` is constantly set to an index, it can lead to unexpected behavior or prevent user interaction, as the menu will continuously try to re-select that option.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}