Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gradio-app/gradio/llms.txt

Use this file to discover all available pages before exploring further.

The custom components workflow focuses on convention over configuration to reduce the number of decisions you as a developer need to make when developing your custom component. That being said, you can still configure some aspects of the custom component package and directory. This guide will cover how.

​
The package name

By default, all custom component packages are called gradio_<component-name> where component-name is the name of the component’s Python class in lowercase. As an example, let’s walkthrough changing the name of a component from gradio_mytextbox to supertextbox.
1

Modify the name in pyproject.toml

Update the name field in the pyproject.toml file:
[project]
name = "supertextbox"
2

Change all occurrences in pyproject.toml

Change all occurrences of gradio_<component-name> to <component-name>:
[tool.hatch.build]
artifacts = ["/backend/supertextbox/templates", "*.pyi"]

[tool.hatch.build.targets.wheel]
packages = ["/backend/supertextbox"]
3

Rename the backend directory

Rename the gradio_<component-name> directory in backend/ to <component-name>:
mv backend/gradio_mytextbox backend/supertextbox
Remember to change the import statement in demo/app.py!

​
Top level Python exports

By default, only the custom component Python class is a top level export. This means that when users type from gradio_<component-name> import ..., the only class that will be available is the custom component class. To add more classes as top level exports, modify the __all__ property in __init__.py: 
from .mytextbox import MyTextbox
from .mytextbox import AdditionalClass, additional_function

__all__ = ['MyTextbox', 'AdditionalClass', 'additional_function']

​
Python dependencies

You can add Python dependencies by modifying the dependencies key in pyproject.toml: 
dependencies = ["gradio", "numpy", "PIL"]
Remember to run gradio cc install when you add dependencies!

​
JavaScript dependencies

You can add JavaScript dependencies by modifying the "dependencies" key in frontend/package.json: 
"dependencies": {
    "@gradio/atoms": "0.2.0-beta.4",
    "@gradio/statustracker": "0.3.0-beta.6",
    "@gradio/utils": "0.2.0-beta.4",
    "your-npm-package": "<version>"
}

​
Directory structure

By default, the CLI will place the Python code in backend and the JavaScript code in frontend. It is not recommended to change this structure since it makes it easy for a potential contributor to look at your source code and know where everything is. However, if you did want to, this is what you would have to do:
1

Move the Python code

Place the Python code in the subdirectory of your choosing. Remember to modify the [tool.hatch.build] and [tool.hatch.build.targets.wheel] in the pyproject.toml to match!
2

Move the JavaScript code

Place the JavaScript code in the subdirectory of your choosing.
3

Add the FRONTEND_DIR property

Add the FRONTEND_DIR property on the component Python class. It must be the relative path from the file where the class is defined to the location of the JavaScript directory.
class SuperTextbox(Component):
    FRONTEND_DIR = "../../frontend/"
The JavaScript and Python directories must be under the same common directory!

​
Best practices

Sticking to the defaults will make it easy for others to understand and contribute to your custom component. After all, the beauty of open source is that anyone can help improve your code! But if you ever need to deviate from the defaults, you know how!

Build docs developers (and LLMs) love

Get started for freeTalk to us