File size: 11,702 Bytes
c840e14 |
1 |
{"guide": {"name": "custom-components-in-five-minutes", "category": "custom-components", "pretty_category": "Custom Components", "guide_index": 1, "absolute_index": 39, "pretty_name": "Custom Components In Five Minutes", "content": "# Custom Components in 5 minutes\n\nGradio 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.\n\nUsers 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.\n\n## Installation\n\nYou will need to have:\n\n* Python 3.10+ (<a href=\"https://www.python.org/downloads/\" target=\"_blank\">install here</a>)\n* pip 21.3+ (`python -m pip install --upgrade pip`)\n* Node.js 20+ (<a href=\"https://nodejs.dev/en/download/package-manager/\" target=\"_blank\">install here</a>)\n* npm 9+ (<a href=\"https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/\" target=\"_blank\">install here</a>)\n* Gradio 5+ (`pip install --upgrade gradio`)\n\n## The Workflow\n\nThe Custom Components workflow consists of 4 steps: create, dev, build, and publish.\n\n1. create: creates a template for you to start developing a custom component.\n2. dev: launches a development server with a sample app & hot reloading allowing you to easily develop your custom component\n3. build: builds a python package containing to your custom component's Python and JavaScript code -- this makes things official!\n4. publish: uploads your package to [PyPi](https://pypi.org/) and/or a sample app to [HuggingFace Spaces](https://hf.co/spaces).\n\nEach of these steps is done via the Custom Component CLI. You can invoke it with `gradio cc` or `gradio component`\n <p class='tip'>\n <span class=\"inline-flex\" style=\"align-items: baseline\">\n <svg class=\"self-center w-5 h-5 mx-1\" xmlns=\"http://www.w3.org/2000/svg\" width=\"800px\" height=\"800px\" viewBox=\"0 0 24 24\" fill=\"currentColor\">\n <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M9.25 18.7089C9.25 18.2894 9.58579 17.9494 10 17.9494H14C14.4142 17.9494 14.75 18.2894 14.75 18.7089C14.75 19.1283 14.4142 19.4684 14 19.4684H10C9.58579 19.4684 9.25 19.1283 9.25 18.7089ZM9.91667 21.2405C9.91667 20.821 10.2525 20.481 10.6667 20.481H13.3333C13.7475 20.481 14.0833 20.821 14.0833 21.2405C14.0833 21.66 13.7475 22 13.3333 22H10.6667C10.2525 22 9.91667 21.66 9.91667 21.2405Z\"/>\n <path d=\"M7.41058 13.8283L8.51463 14.8807C8.82437 15.1759 9 15.5875 9 16.0182C9 16.6653 9.518 17.1899 10.157 17.1899H13.843C14.482 17.1899 15 16.6653 15 16.0182C15 15.5875 15.1756 15.1759 15.4854 14.8807L16.5894 13.8283C18.1306 12.3481 18.9912 10.4034 18.9999 8.3817L19 8.29678C19 4.84243 15.866 2 12 2C8.13401 2 5 4.84243 5 8.29678L5.00007 8.3817C5.00875 10.4034 5.86939 12.3481 7.41058 13.8283Z\"/>\n </svg>\n <span><strong>Tip:</strong></span>\n </span>\n 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`.\n </p>\n \n\n## 1. create\n\nBootstrap a new template by running the following in any working directory:\n\n```bash\ngradio cc create MyComponent --template SimpleTextbox\n```\n\nInstead of `MyComponent`, give your component any name.\n\nInstead of `SimpleTextbox`, you can use any Gradio component as a template. `SimpleTextbox` is actually a special component that a stripped-down version of the `Textbox` component that makes it particularly useful when creating your first custom component.\nSome other components that are good if you are starting out: `SimpleDropdown`, `SimpleImage`, or `File`.\n <p class='tip'>\n <span class=\"inline-flex\" style=\"align-items: baseline\">\n <svg class=\"self-center w-5 h-5 mx-1\" xmlns=\"http://www.w3.org/2000/svg\" width=\"800px\" height=\"800px\" viewBox=\"0 0 24 24\" fill=\"currentColor\">\n <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M9.25 18.7089C9.25 18.2894 9.58579 17.9494 10 17.9494H14C14.4142 17.9494 14.75 18.2894 14.75 18.7089C14.75 19.1283 14.4142 19.4684 14 19.4684H10C9.58579 19.4684 9.25 19.1283 9.25 18.7089ZM9.91667 21.2405C9.91667 20.821 10.2525 20.481 10.6667 20.481H13.3333C13.7475 20.481 14.0833 20.821 14.0833 21.2405C14.0833 21.66 13.7475 22 13.3333 22H10.6667C10.2525 22 9.91667 21.66 9.91667 21.2405Z\"/>\n <path d=\"M7.41058 13.8283L8.51463 14.8807C8.82437 15.1759 9 15.5875 9 16.0182C9 16.6653 9.518 17.1899 10.157 17.1899H13.843C14.482 17.1899 15 16.6653 15 16.0182C15 15.5875 15.1756 15.1759 15.4854 14.8807L16.5894 13.8283C18.1306 12.3481 18.9912 10.4034 18.9999 8.3817L19 8.29678C19 4.84243 15.866 2 12 2C8.13401 2 5 4.84243 5 8.29678L5.00007 8.3817C5.00875 10.4034 5.86939 12.3481 7.41058 13.8283Z\"/>\n </svg>\n <span><strong>Tip:</strong></span>\n </span>\n Run `gradio cc show` to get a list of available component templates.\n </p>\n \n\nThe `create` command will:\n\n1. Create a directory with your component's name in lowercase with the following structure:\n```directory\n- backend/ <- The python code for your custom component\n- frontend/ <- The javascript code for your custom component\n- demo/ <- A sample app using your custom component. Modify this to develop your component!\n- pyproject.toml <- Used to build the package and specify package metadata.\n```\n\n2. Install the component in development mode\n\nEach of the directories will have the code you need to get started developing!\n\n## 2. dev\n\nOnce you have created your new component, you can start a development server by `entering the directory` and running\n\n```bash\ngradio cc dev\n```\n\nYou'll see several lines that are printed to the console.\nThe most important one is the one that says:\n\n> Frontend Server (Go here): http://localhost:7861/\n\nThe port number might be different for you.\nClick on that link to launch the demo app in hot reload mode.\nNow, you can start making changes to the backend and frontend you'll see the results reflected live in the sample app!\nWe'll go through a real example in a later guide.\n <p class='tip'>\n <span class=\"inline-flex\" style=\"align-items: baseline\">\n <svg class=\"self-center w-5 h-5 mx-1\" xmlns=\"http://www.w3.org/2000/svg\" width=\"800px\" height=\"800px\" viewBox=\"0 0 24 24\" fill=\"currentColor\">\n <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M9.25 18.7089C9.25 18.2894 9.58579 17.9494 10 17.9494H14C14.4142 17.9494 14.75 18.2894 14.75 18.7089C14.75 19.1283 14.4142 19.4684 14 19.4684H10C9.58579 19.4684 9.25 19.1283 9.25 18.7089ZM9.91667 21.2405C9.91667 20.821 10.2525 20.481 10.6667 20.481H13.3333C13.7475 20.481 14.0833 20.821 14.0833 21.2405C14.0833 21.66 13.7475 22 13.3333 22H10.6667C10.2525 22 9.91667 21.66 9.91667 21.2405Z\"/>\n <path d=\"M7.41058 13.8283L8.51463 14.8807C8.82437 15.1759 9 15.5875 9 16.0182C9 16.6653 9.518 17.1899 10.157 17.1899H13.843C14.482 17.1899 15 16.6653 15 16.0182C15 15.5875 15.1756 15.1759 15.4854 14.8807L16.5894 13.8283C18.1306 12.3481 18.9912 10.4034 18.9999 8.3817L19 8.29678C19 4.84243 15.866 2 12 2C8.13401 2 5 4.84243 5 8.29678L5.00007 8.3817C5.00875 10.4034 5.86939 12.3481 7.41058 13.8283Z\"/>\n </svg>\n <span><strong>Tip:</strong></span>\n </span>\n 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.\n </p>\n \n\n## 3. build\n\nOnce you are satisfied with your custom component's implementation, you can `build` it to use it outside of the development server.\n\nFrom your component directory, run:\n\n```bash\ngradio cc build\n```\n\nThis will create a `tar.gz` and `.whl` file in a `dist/` subdirectory.\nIf 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!\n\nThe `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`. You can read more about the documentation generator in [the dedicated guide](https://gradio.app/guides/documenting-custom-components).\n\n## 4. publish\n\nRight now, your package is only available on a `.whl` file on your computer.\nYou can share that file with the world with the `publish` command!\n\nSimply run the following command from your component directory:\n\n```bash\ngradio cc publish\n```\n\nThis will guide you through the following process:\n\n1. Upload your distribution files to PyPi. This is optional. If you decide to upload to PyPi, you will need a PyPI username and password. You can get one [here](https://pypi.org/account/register/).\n2. Upload a demo of your component to hugging face spaces. This is also optional.\n\n\nHere is an example of what publishing looks like:\n\n<video autoplay muted loop>\n <source src=\"https://gradio-builds.s3.amazonaws.com/assets/text_with_attachments_publish.mov\" type=\"video/mp4\" />\n</video>\n\n\n## Conclusion\n\nNow that you know the high-level workflow of creating custom components, you can go in depth in the next guides!\nAfter reading the guides, check out this [collection](https://huggingface.co/collections/gradio/custom-components-65497a761c5192d981710b12) of custom components on the HuggingFace Hub so you can learn from other's code.\n <p class='tip'>\n <span class=\"inline-flex\" style=\"align-items: baseline\">\n <svg class=\"self-center w-5 h-5 mx-1\" xmlns=\"http://www.w3.org/2000/svg\" width=\"800px\" height=\"800px\" viewBox=\"0 0 24 24\" fill=\"currentColor\">\n <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M9.25 18.7089C9.25 18.2894 9.58579 17.9494 10 17.9494H14C14.4142 17.9494 14.75 18.2894 14.75 18.7089C14.75 19.1283 14.4142 19.4684 14 19.4684H10C9.58579 19.4684 9.25 19.1283 9.25 18.7089ZM9.91667 21.2405C9.91667 20.821 10.2525 20.481 10.6667 20.481H13.3333C13.7475 20.481 14.0833 20.821 14.0833 21.2405C14.0833 21.66 13.7475 22 13.3333 22H10.6667C10.2525 22 9.91667 21.66 9.91667 21.2405Z\"/>\n <path d=\"M7.41058 13.8283L8.51463 14.8807C8.82437 15.1759 9 15.5875 9 16.0182C9 16.6653 9.518 17.1899 10.157 17.1899H13.843C14.482 17.1899 15 16.6653 15 16.0182C15 15.5875 15.1756 15.1759 15.4854 14.8807L16.5894 13.8283C18.1306 12.3481 18.9912 10.4034 18.9999 8.3817L19 8.29678C19 4.84243 15.866 2 12 2C8.13401 2 5 4.84243 5 8.29678L5.00007 8.3817C5.00875 10.4034 5.86939 12.3481 7.41058 13.8283Z\"/>\n </svg>\n <span><strong>Tip:</strong></span>\n </span>\n If you want to start off from someone else's custom component see this [guide](./frequently-asked-questions#do-i-always-need-to-start-my-component-from-scratch).\n </p>\n \n", "tags": [], "spaces": [], "url": "/guides/custom-components-in-five-minutes/", "contributor": null}} |