Tutorial | Create an Editor Add-on that Imports Icons from a Library

In this tutorial, we’ll show you how to create an editor add-on from scratch. This add-on lets users import icons from a predefined library directly into their site by uploading them to the site's media files and applying them to a selected element in the Wix Editor.

add-on

We'll follow these steps to build the app:

  1. Create a React project using Vite.
  2. Run the project locally.
  3. Set up your app in the Wix Custom Apps page.
  4. Test the app on a site.

While we’re using Vite as the build tool, you can choose any local development server that suits your needs.

Before you begin

Before getting started, make sure that:

  • You are signed into your Wix account.
  • You have Node.js 20 or higher installed.
  • You have a Wix site that you can use for testing purposes. If you don’t have one yet, create a new site.

Step 1 | Set up a React project

Start by setting up a new React project with Vite. We’ll follow these steps:

  1. Bootstrap the React project.
  2. Install dependencies.
  3. Configure Vite.
  4. Create React application files.

Bootstrap a React project with Vite

  1. Run the following command in your terminal:

    Copy

  2. Navigate to your new project folder:

    Copy

Add dependencies in the package.json file and install them

Next, we'll install the required dependencies for the app. These include:

  • @wix/design-system – Ensures the UI follows Wix’s design guidelines, providing components like Box, Text, and Button.
  • @wix/editor – Enables interaction with the Wix Editor, including selecting and modifying site elements.
  • @wix/media – Handles uploading the selected icon to Wix Media storage for use on the site.
  • @wix/sdk – Provides API access to Wix services like files and elements, allowing the add-on to modify editor elements.
  • vite-plugin-mkcert – Enables HTTPS support for local development, which is required for secure communication with Wix.
  • vite-plugin-node-polyfills – Ensures compatibility with Node.js APIs within a Vite-based front-end environment.
  • @emotion/react & @emotion/styled – Required by Material UI for styling components dynamically.
  • @mui/icons-material & @mui/material – Provides the Material UI components and icons used for the icon selection interface.

  1. Open package.json and add the following dependencies under "dependencies":

    Copy

  2. Under "devDependencies", add:

    Copy

  3. Install the dependencies:

    Copy

Configure Vite

Update the vite.config.ts file in your project root with the following code to enable HTTPS for local development and add Node.js polyfills:

Copy

Create application files

We'll now create the core application files needed for the project:

  • main.tsx: This is the entry point of your application. Update it to import Wix Design System's style sheet.
  • App.tsx: This file contains the main structure of the app, showing a button for adding icons, a loader for upload states, and a message for the user.
  • Icons.tsx: Displays the available icons in the library using Material UI's IconButton. Icons can be selected, and a state is updated for the chosen icon.
  • useIconsManager.tsx: Manages icon selection, uploading, and handling interactions with the Wix media service. This includes logic for converting the selected icon into an SVG and uploading it to site's media files, and applying it to the selected element in the Wix editor.

Ensure your src directory includes App.tsx and main.tsx files and update their content as follows:

src/main.tsx
Copy
src/App.tsx
Copy

In your src directory create the following files:

src/Icons.tsx
Copy
src/useIconsManager.tsx
Copy

Step 2 | Run your project

Start the development server by running the following command in your terminal:

Copy

Once the server starts, Vite will provide a local development URL (typically https://localhost:5173). Open your browser and navigate to this URL to preview your app.

You can view and interact with the UI in your browser. However, the add-on functionality will not work outside the Wix Editor. In the next step, we'll set it up as a Wix app extension so we can test it properly within the Wix Editor.

Step 3 | Set up your app in the Custom Apps page

To make the add-on available for installation on sites, we'll create a Wix app and set up an add-on extension.

  1. In the Custom Apps page, go to My Apps, and then click Create New App.

  2. Select Build from scratch.

  3. In the left sidebar, select Extensions, and then click Create Extension.
    A panel opens, showing the available extension types.

  4. Find the Editor Add-on extension and click Create.

  5. Configure the add-on’s basic data:

    • Add-on name: Enter a name for your add-on, for example, Get Icons.
    • Panel URL: Enter the localhost URL provided by Vite in the previous step.
    • Panel width: Choose Small to match the size of most native editor panels.
    • Panel height: Set the height to 400 px.

  6. Under Market listing, fill in the Teaser field with a short description, such as Import icons from the Material UI library.

  7. Click Save.

  8. Add the required permissions to the app so it can access a site's media files:

    1. In the left sidebar, select Permissions, and then click Add Permissions.

    2. Find the Manage Media Manager permission scope, select it, and then click Save.

Your add-on extension is now available for installation on a site.

Step 4 | Test your add-on in the editor

To test the add-on, we'll install it on a site:

  1. In your app's dashboard, click Test Your App, and then click Editor.

  2. Select a site on which you want to install the app, and click Add to Site.

  3. When prompted for consent, click Agree & Add.
    Your app is now installed on a site and your add-on is available in the editor.

  4. In the editor's Tools menu, select Editor Add-ons, and then select your add-on.
    Your add-on’s panel is displayed.

  5. Add an image element to the page and select it.

  6. Select one of the icons in the add-on panel and click Add Icon.
    The add-on should successfully upload the icon to the site's media files and apply it to the selected image element.

What’s next

Now that you've learned how to set up a self-hosted editor add-on, you can start thinking about building your own app. Here are a few resources to get you started:

Did this help?