streamlit · sfc-gh-dmatthews · Dec 4, 2025 · Dec 5, 2025 · Dec 5, 2025 · Dec 6, 2025
@@ -1,62 +1,52 @@
 ---
-title: Components
+title: Custom Components
 slug: /develop/concepts/custom-components
-description: Learn how to build and use custom Streamlit components to extend app functionality with third-party Python modules and custom UI elements.
-keywords: custom components, third-party modules, component development, extend functionality, custom UI, component integration, Streamlit components
+description: Learn about Streamlit custom components - powerful extensions that unlock capabilities beyond built-in widgets using web technologies.
+keywords: custom components, component development, extend streamlit, web components, custom widgets, component architecture
 ---
 
 # Custom Components
 
-Components are third-party Python modules that extend what's possible with Streamlit.
+Custom Components are powerful extensions for Streamlit that unlock capabilities beyond the built-in widgets. They let you integrate any web technology—from advanced data visualizations to specialized input controls to complete mini-applications—directly into your Streamlit apps.
 
-## How to use a Component
+## Getting started
 
-Components are super easy to use:
+<TileContainer>
 
-1. Start by finding the Component you'd like to use. Two great resources for this are:
-   - The [Component gallery](https://streamlit.io/components)
-   - [This thread](https://discuss.streamlit.io/t/streamlit-components-community-tracker/4634),
-     by Fanilo A. from our forums.
+<RefCard href="/develop/concepts/custom-components/overview">
 
-2. Install the Component using your favorite Python package manager. This step and all following
-   steps are described in your component's instructions.
+<h4>Overview of Custom Components</h4>
 
-   For example, to use the fantastic [AgGrid
-   Component](https://github.com/PablocFonseca/streamlit-aggrid), you first install it with:
+Learn what custom components are, when to use them, and understand the differences between v1 and v2 approaches.
 
-   ```python
-   pip install streamlit-aggrid
-   ```
+</RefCard>
 
-3. In your Python code, import the Component as described in its instructions. For AgGrid, this step
-   is:
+<RefCard href="/develop/concepts/custom-components/v2">
 
-   ```python
-   from st_aggrid import AgGrid
-   ```
+<h4>Components v2</h4>
 
-4. ...now you're ready to use it! For AgGrid, that's:
+The next generation of custom components with enhanced capabilities, bidirectional communication, and simplified development.
 
-   ```python
-   AgGrid(my_dataframe)
-   ```
+</RefCard>
 
-## Making your own Component
+<RefCard href="/develop/concepts/custom-components/v1">
 
-If you're interested in making your own component, check out the following resources:
+<h4>Components v1</h4>
 
-- [Create a Component](/develop/concepts/custom-components/create)
-- [Publish a Component](/develop/concepts/custom-components/publish)
-- [Components API](/develop/concepts/custom-components/intro)
-- [Blog post for when we launched Components!](https://blog.streamlit.io/introducing-streamlit-components/)
+The original custom components framework. Learn how to use and build v1 components.
 
-Alternatively, if you prefer to learn using videos, our engineer Tim Conkling has put together some
-amazing tutorials:
+</RefCard>
 
-##### Video tutorial, part 1
+<RefCard href="/develop/concepts/custom-components/publish">
 
-<YouTube videoId="BuD3gILJW-Q" />
+<h4>Publishing Components</h4>
 
-##### Video tutorial, part 2
+Learn how to package and distribute your custom components to the community.
 
-<YouTube videoId="QjccJl_7Jco" />
+</RefCard>
+
+</TileContainer>
+
+## Component gallery
+
+Explore the [Community Component Gallery](https://streamlit.io/components) to discover components built by the Streamlit community.
@@ -0,0 +1,62 @@
+---
+title: Components v1
+slug: /develop/concepts/custom-components/components-v1
+description: Learn how to build and use custom Streamlit components to extend app functionality with third-party Python modules and custom UI elements.
+keywords: custom components, third-party modules, component development, extend functionality, custom UI, component integration, Streamlit components
+---
+
+# Custom Components
+
+Components are third-party Python modules that extend what's possible with Streamlit.
+
+## How to use a Component
+
+Components are super easy to use:
+
+1. Start by finding the Component you'd like to use. Two great resources for this are:
+   - The [Component gallery](https://streamlit.io/components)
+   - [This thread](https://discuss.streamlit.io/t/streamlit-components-community-tracker/4634),
+     by Fanilo A. from our forums.
+
+2. Install the Component using your favorite Python package manager. This step and all following
+   steps are described in your component's instructions.
+
+   For example, to use the fantastic [AgGrid
+   Component](https://github.com/PablocFonseca/streamlit-aggrid), you first install it with:
+
+   ```python
+   pip install streamlit-aggrid
+   ```
+
+3. In your Python code, import the Component as described in its instructions. For AgGrid, this step
+   is:
+
+   ```python
+   from st_aggrid import AgGrid
+   ```
+
+4. ...now you're ready to use it! For AgGrid, that's:
+
+   ```python
+   AgGrid(my_dataframe)
+   ```
+
+## Making your own Component
+
+If you're interested in making your own component, check out the following resources:
+
+- [Create a Component](/develop/concepts/custom-components/create)
+- [Publish a Component](/develop/concepts/custom-components/publish)
+- [Components API](/develop/concepts/custom-components/intro)
+- [Blog post for when we launched Components!](https://blog.streamlit.io/introducing-streamlit-components/)
+
+Alternatively, if you prefer to learn using videos, our engineer Tim Conkling has put together some
+amazing tutorials:
+
+##### Video tutorial, part 1
+
+<YouTube videoId="BuD3gILJW-Q" />
+
+##### Video tutorial, part 2
+
+<YouTube videoId="QjccJl_7Jco" />
@@ -1,6 +1,6 @@
 ---
 title: Intro to custom components
-slug: /develop/concepts/custom-components/intro
+slug: /develop/concepts/custom-components/components-v1/intro
 description: Learn to develop Streamlit custom components with static and bi-directional communication between Python and JavaScript for extended functionality.
 keywords: custom component development, static components, bi-directional components, Python JavaScript communication, component API, component development
 ---

@@ -1,6 +1,6 @@
 ---
 title: Create a Component
-slug: /develop/concepts/custom-components/create
+slug: /develop/concepts/custom-components/components-v1/create
 description: Step-by-step guide to creating custom Streamlit components from scratch, including setup, development environment, and component structure.
 keywords: create component, component development, component setup, development environment, component structure, custom component creation, build components
 ---

@@ -1,6 +1,6 @@
 ---
 title: Limitations of custom components
-slug: /develop/concepts/custom-components/limitations
+slug: /develop/concepts/custom-components/components-v1/limitations
 description: Understand the limitations and constraints of Streamlit custom components including iframe restrictions and differences from base Streamlit functionality.
 keywords: component limitations, iframe restrictions, component constraints, custom component issues, component differences, development limitations
 ---

@@ -0,0 +1,67 @@
+---
+title: Custom components v2
+slug: /develop/concepts/custom-components/components-v2
+description: Learn about Streamlit custom components v2 - the next generation framework with enhanced capabilities, bidirectional communication, and simplified development.
+keywords: custom components v2, next generation components, bidirectional communication, enhanced capabilities, modern component development
+---
+
+# Custom components v2
+
+Components v2 represents a reimagining of how custom components work in Streamlit. It's designed to unlock new capabilities and dramatically simplify the development experience. For command reference, see the [API Reference](/develop/api-reference/custom-components).
+
+## Getting started
+
+<TileContainer>
+
+<RefCard href="/develop/concepts/custom-components/components-v2/quickstart">
+
+<h4>Quickstart examples</h4>
+
+Get started quickly with practical examples showing interactive buttons, data exchange, and complete component implementations.
+
+</RefCard>
+
+<RefCard href="/develop/concepts/custom-components/components-v2/create">
+
+<h4>Create components</h4>
+
+Learn the basics of registering and mounting v2 components with inline development.
+
+</RefCard>
+
+<RefCard href="/develop/concepts/custom-components/components-v2/state-and-triggers">
+
+<h4>State vs triggers</h4>
+
+Understand the two communication mechanisms for building interactive components.
+
+</RefCard>
+
+<RefCard href="/develop/concepts/custom-components/components-v2/theming">
+
+<h4>Theming & styling</h4>
+
+Make your components look great with Streamlit's theme integration and CSS custom properties.
+
+</RefCard>
+
+<RefCard href="/develop/concepts/custom-components/components-v2/package-based">
+
+<h4>Package-based components</h4>
+
+Build complex components with modern frontend tooling, TypeScript, and external dependencies.
+
+</RefCard>
+
+</TileContainer>
+
+## Migration from v1 to v2
+
+If you have existing v1 components, check out these migration examples:
+
+- [streamlit-bokeh v2 migration](https://github.com/streamlit/streamlit-bokeh/pull/40)
+- [streamlit-pdf v2 migration](https://github.com/streamlit/streamlit-pdf/pull/25)
+
+## What's next?
+
+Ready to build your first v2 component? Start with the [Quickstart examples](/develop/concepts/custom-components/components-v2/quickstart) to see practical implementations, then dive into the [Create components](/develop/concepts/custom-components/components-v2/create) guide to learn the fundamentals.