---
updatedAt: 2026-10-01T15:55:22.000Z
agentTools:
projectIndex: https://docs.median.co/llms.txt
---
# Custom Icons
Learn how to upload custom SVG icons with Fontello
Median apps include built-in icon libraries for native navigation menus. When you need icons that match your brand, such as your logo, a product-specific symbol, or a custom illustration style, you can upload your own **SVG icons** to the Median App Studio. Median packages them into an icon font with Fontello, and you can then use them anywhere native navigation icons are supported in your iOS and Android app.
This guide explains how to prepare your SVG files, import them through Fontello, and apply custom icons to your app's navigation.
## What you can use custom icons for
After you upload custom icons once, they become available to every native navigation component in your app:
* [Bottom Tab Bar](https://docs.median.co/docs/bottom-tab-bar) tab icons
* [Sidebar Navigation](https://docs.median.co/docs/sidebar-navigation-menu) menu item icons
* [Top Navigation Bar](https://docs.median.co/docs/top-navigation-bar) buttons, including [Custom Buttons](https://docs.median.co/docs/add-custom-buttons)
## Before you begin
Make sure you have the following:
* A Median app in Median App Studio that you have permission to edit.
* One or more icons saved as `.svg` files.
* A desktop browser. The Fontello import panel works best on a large screen.
### Prepare your SVG files
Fontello converts SVG artwork into font glyphs, and fonts can only render a single solid color. Preparing your files correctly prevents most import problems.
| Requirement | Why it matters |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Use filled shapes, not strokes.** Convert all strokes and lines to outlines (in Figma: *Outline stroke*; in Illustrator: *Object → Path → Outline Stroke*). | Fonts ignore stroke data, so stroked lines disappear or render incorrectly. |
| **Flatten and combine paths** into a single compound path where possible. | Overlapping or grouped shapes can import as empty or inverted glyphs. |
| **Use a square artboard** (for example, 24 × 24 or 1000 × 1000) with the icon centered. | Keeps icons consistently sized and aligned across your navigation. |
| **Remove colors, gradients, masks, images, and text elements.** | Icon fonts are single-color. The color is applied by your app's theme settings. |
| **Use clear, lowercase, hyphenated file names** (for example, `shopping-bag.svg`). | The file name typically becomes the icon name you reference later. |
## Add custom icons in App Studio
### Step 1: Open the Tab Bar Visual Editor
1. Sign in to Median App Studio and open the app you want to edit.
2. Click **Edit App**.
3. In the configuration menu, select **Native Navigation**.
4. Select the **Tab Bar you **want to edit.
5. Scroll to the **Visual Editor** section at the bottom of the page.
If your app doesn't have a bottom tab bar yet, click **Add Bottom Tab Bar**.
### Step 2: Open the custom icon uploader
1. In the visual editor, click the tab icon you want to replace.
2. In the pop-up window, click the **icon**.
3. At the top of the icon picker, select **Custom**, then click **Add Custom Icons**.
The Fontello editor opens in the right-hand panel.
### Step 3: Import your SVG files into Fontello
1. In the Fontello panel, click the **wrench icon** (settings).
2. Click **Import**, then select the `.svg` files you want to upload. You can select several files at once.
Your imported icons appear in a **Custom Icons** section at the top of the Fontello panel.
### Step 4: Configure the Fontello font settings
Before you export, confirm the following settings. Median uses them to locate and load your icons, so incorrect values cause icons to be missing in your app.
| Setting | Required value |
| ------------------------------------- | -------------- |
| Font name (next to the wrench icon) | `custom-icons` |
| CSS prefix | `icon-` |
| "Add after icon name" (suffix option) | **Unchecked** |
### **Important:** Do not rename the font. The font name must always be `custom-icons`, including when you add more icons later.
### Step 5: Select and export your icons
1. Click each icon you want to include so it's highlighted. Only selected icons are exported.
2. Click **Export font**.
Fontello closes and you return to App Studio. Your custom icons now appear under the **Custom** tab in the icon picker.
### Step 6: Apply a custom icon and test your app
1. In the icon picker, select the **Custom** tab and choose your icon.
2. Save your changes.
3. Preview your app in the App Studio simulator, or rebuild and install it on a device, to confirm that the icon displays correctly on both iOS and Android.
## Video walkthrough
Watch the full process of uploading and applying custom icons:
## Use custom icons in dynamic menus
If you set navigation menus at runtime with the [Median JavaScript Bridge](https://docs.median.co/docs/javascript-bridge), for example with a [Dynamic Tab Menu](https://docs.median.co/docs/dynamic-tab-menu) or [Dynamic Menu Items](https://docs.median.co/docs/dynamic-menu-items), you can reference your uploaded icons in the `icon` field instead of a built-in icon class such as `fas fa-cloud`.
```javascript
median.tabNavigation.setTabs({
enabled: true,
items: [
{
icon: "custom-icons icon-shopping-bag", // custom icon uploaded via Fontello
label: "Shop",
url: "https://example.com/shop"
},
{
icon: "fas fa-user", // built-in icon
label: "Account",
url: "https://example.com/account"
}
]
});
```
## Add, update, or remove custom icons
To change your icon set later, reopen the uploader (**Custom → Add Custom Icons**). Your previously exported icons load in Fontello.
* **Add icons:** Import new SVG files, select them alongside your existing icons, and click **Export font**.
* **Replace an icon:** Delete the old glyph, import the updated SVG with the same file name, select it, and export.
* **Remove icons:** Deselect the icons you no longer need before you export.
### **Warning:** Every export replaces the entire custom icon set. Any icon that isn't selected at export time is removed, and navigation items that use it will no longer display an icon. Always reselect every icon you still use before you export.
## Troubleshooting
| Problem | Likely cause | Solution |
| ------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Icon doesn't appear in the app | The font name or CSS prefix is wrong | Set the font name to `custom-icons`, the CSS prefix to `icon-`, and uncheck the suffix option. Then export again. |
| Icon is blank or a solid square | The SVG uses strokes, masks, or unsupported elements | Convert strokes to outlines, flatten the paths, and re-import the file. |
| Icon looks inverted or has missing sections | Overlapping or opposing paths | Combine shapes into a single compound path in your design tool. |
| Icon is too small, too large, or off-center | The artboard isn't square or has extra padding | Use a square artboard with the icon centered and consistent padding. |
| Previously uploaded icons disappeared | The icons weren't selected during the most recent export | Reopen Fontello, select all the icons you need, and export again. |
| Changes don't appear on a device | The installed build is out of date | Rebuild the app, or check the App Studio simulator first. |
## FAQ
**What file format do custom icons use?**
Upload icons as SVG files. Fontello converts them into an icon font that Median bundles into your app.
**Can custom icons have more than one color?**
No. Icon fonts are single-color. The icon color comes from your navigation styling and [Theme Colors](https://docs.median.co/docs/theme-colors), including [Dark Mode](https://docs.median.co/docs/dark-mode) settings.
**Do custom icons work on both iOS and Android?**
Yes. Custom icons are part of your app configuration and are applied to both platforms.
**Is this the same as my app icon?**
No. This page covers icons inside your app's navigation menus. To change the icon shown on the device home screen and in app stores, see [App Icon](https://docs.median.co/docs/app-icon).
**Can I mix custom icons with built-in icons?**
Yes. You can use built-in and custom icons in the same menu.