Skip to main content
Gradio includes the ability for developers to create their own custom components and use them in Gradio apps. You can publish your components as Python packages so that other users can use them as well. Users will be able to use all of Gradio’s existing functions, such as gr.Blocks, gr.Interface, API usage, themes, etc. with custom components. This guide will cover how to get started making custom components.

​
Installation

You will need to have:

​
The workflow

The custom components workflow consists of 4 steps: create, dev, build, and publish.
1

Create

Creates a template for you to start developing a custom component.
2

Dev

Launches a development server with a sample app and hot reloading allowing you to easily develop your custom component.
3

Build

Builds a Python package containing your custom component’s Python and JavaScript code.
4

Publish

Uploads your package to PyPI and/or a sample app to HuggingFace Spaces.
Each of these steps is done via the custom component CLI. You can invoke it with gradio cc or gradio component.
Run gradio cc --help to get a help menu of all available commands. There are some commands that are not covered in this guide. You can also append --help to any command name to bring up a help page for that command, e.g. gradio cc create --help.

​
Step 1: Create

Bootstrap a new template by running the following in any working directory: 
gradio cc create MyComponent --template SimpleTextbox
Instead of MyComponent, give your component any name. Instead of SimpleTextbox, you can use any Gradio component as a template. SimpleTextbox is actually a special component that is a stripped-down version of the Textbox component that makes it particularly useful when creating your first custom component. Some other components that are good if you are starting out: SimpleDropdown, SimpleImage, or File.
Run gradio cc show to get a list of available component templates.

​
What gets created

The create command will:
  1. Create a directory with your component’s name in lowercase with the following structure:
- backend/     ← The Python code for your custom component
- frontend/    ← The JavaScript code for your custom component
- demo/        ← A sample app using your custom component. Modify this to develop your component!
- pyproject.toml ← Used to build the package and specify package metadata
  1. Install the component in development mode
Each of the directories will have the code you need to get started developing!

​
Step 2: Dev

Once you have created your new component, you can start a development server by entering the directory and running: 
gradio cc dev
You’ll see several lines that are printed to the console. The most important one is the one that says: 
Frontend Server (Go here): http://localhost:7861/
The port number might be different for you. Click on that link to launch the demo app in hot reload mode. Now, you can start making changes to the backend and frontend and you’ll see the results reflected live in the sample app!
You don’t have to run dev mode from your custom component directory. The first argument to dev mode is the path to the directory. By default it uses the current directory.

​
Step 3: Build

Once you are satisfied with your custom component’s implementation, you can build it to use it outside of the development server. From your component directory, run: 
gradio cc build
This will create a tar.gz and .whl file in a dist/ subdirectory. If you or anyone installs that .whl file (pip install <path-to-whl>) they will be able to use your custom component in any Gradio app! The build command will also generate documentation for your custom component. This takes the form of an interactive space and a static README.md. You can disable this by passing --no-generate-docs.

​
Step 4: Publish

Right now, your package is only available on a .whl file on your computer. You can share that file with the world with the publish command! Simply run the following command from your component directory: 
gradio cc publish
This will guide you through the following process:
  1. Upload your distribution files to PyPI. This makes it easier to upload the demo to Hugging Face spaces. Otherwise your package must be at a publicly available URL. If you decide to upload to PyPI, you will need a PyPI username and password. You can get one here.
  2. Upload a demo of your component to Hugging Face Spaces. This is also optional.

​
Next steps

Now that you know the high-level workflow of creating custom components, you can go in depth in the following guides: After reading the guides, check out this collection of custom components on the HuggingFace Hub so you can learn from other developers’ code.