# Export and install

> How the theme editor writes an unpacked theme folder, exports a manifest.json or ZIP, and builds a Firefox package with the keys Gecko renders.

Canonical: https://docs.extension.dev/themes/export
This page as Markdown: https://docs.extension.dev/themes/export.md
Section: Themes
Siblings: [Theme builder](https://docs.extension.dev/themes.md) · [The editor](https://docs.extension.dev/themes/editor.md) · [Colors](https://docs.extension.dev/themes/colors.md) · [Presets and palettes](https://docs.extension.dev/themes/presets.md) · [Images and tints](https://docs.extension.dev/themes/images.md) · [Import a theme](https://docs.extension.dev/themes/import.md) · [Firefox preview](https://docs.extension.dev/themes/firefox-preview.md) · [Publish and hand off](https://docs.extension.dev/themes/publish.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Export and install

Export turns the editor state into files Chrome or Firefox can load. Reach
for it when the preview looks right and you want the theme in a browser, in
a ZIP for the store, or in a folder you can edit by hand.

## Quick start

1. Open **Theme settings** in the editor and give the theme a name.
2. Under **Export**, click **Install this theme** and pick an empty folder.
   The editor writes the unpacked theme there.
3. Open `chrome://extensions`, turn on Developer mode, click **Load
   unpacked** and pick that folder.


## How it works

**Install this theme.** The button writes the unpacked folder through the
browser's directory picker, so it renders only where that API exists,
which today means Chromium. The toast then reads "Theme folder written"
with the Load unpacked steps and the folder name. In a browser without the
picker the section says so and offers the ZIP instead. Closing the picker
writes nothing.

**Export ZIP.** The ZIP holds `manifest.json`, every image under
`images/` as PNG, and a `README.txt` with the Load unpacked steps. The file
is named after the theme, with spaces turned into underscores. The section
shows an estimated ZIP size before you click.

**Export manifest.json and Copy manifest JSON.** The first downloads the
manifest alone. The second puts the same JSON on the clipboard.

**The manifest.** The export is a manifest version 3 theme. Colors are
written as RGB arrays, tints as HSL triples, and images by their path under
`images/`. Keys imported from another theme that the editor does not edit
are written back as they came.

**Export is validated.** An empty theme name blocks every export, because
Chrome refuses a manifest without one. A version that is not one to four
dot-separated integers from 0 to 65535 blocks it too. The field is marked
and the toast reads "Export blocked: fix the highlighted theme information
first."

**Reset to default.** The button asks for confirmation, then clears the
theme and the undo history. It cannot be undone.

**Export Firefox ZIP.** Firefox themes use different keys, so the Firefox
package carries only what Gecko can render. It is a manifest version 2 theme
with a Gecko id built from the theme name, twelve colors mapped to their
Gecko names, and the frame image if there is one. Eight fields are dropped;
the section lists them under "Not in the Firefox package" and a toast
repeats the list after the download. The README points to
`about:debugging` for a temporary install. The preview stays Chrome, so
nothing in the editor shows how Firefox paints the result.

## Reference

| Action | Produces |
| --- | --- |
| Install this theme | An unpacked folder written on disk, Chromium only |
| Export ZIP | `<name>.zip` with `manifest.json`, `images/*.png`, `README.txt` |
| Export manifest.json | `manifest.json` |
| Copy manifest JSON | The manifest on the clipboard |
| Export Firefox ZIP | `<name>-firefox.zip` with `manifest.json`, `images/frame.png` when set, `README.txt` |
| Reset to default | The default theme, after confirmation |

| Validation | Rule |
| --- | --- |
| Theme name | Not empty |
| Version | One to four dot-separated integers, each 0 to 65535 |

| Editor field | Firefox key |
| --- | --- |
| Active frame | `frame` |
| Inactive frame | `frame_inactive` |
| Inactive tab text | `tab_background_text` |
| Toolbar background | `toolbar` |
| Active tab text | `tab_text` |
| Toolbar text | `bookmark_text` |
| NTP background | `ntp_background` |
| NTP text | `ntp_text` |
| Toolbar-level text | `toolbar_text` |
| Toolbar icons | `icons` |
| Omnibox text | `toolbar_field_text` |
| Suggestions background | `popup` |

| Dropped from the Firefox package | Why |
| --- | --- |
| Inactive-window tab text | Firefox has no separate color for it |
| Button background | Firefox only colors the hover and active states |
| NTP link | Firefox themes cannot set it |
| Tints | A Chrome-only hue shift |
| Toolbar image | No toolbar image slot |
| Tab background image | No tab image slot |
| NTP background image | Firefox themes cannot set one |
| NTP attribution image | Chrome-only |

The Gecko id is the theme name lowercased, non-alphanumerics turned into
hyphens, followed by `@themes.extension.dev`. A frame that was never set
exports as `#202124` and inactive tab text as `#9aa0a6`.

## When it fails

- **"Export blocked: fix the highlighted theme information first."** The
  name is empty or the version is invalid. Fix the marked field in Theme
  settings.
- **Install this theme is missing.** The browser has no directory picker.
  Use Export ZIP, unzip it, and Load unpacked the folder.
- **"This browser cannot write a folder, so the ZIP was downloaded
  instead."** Same cause. Unzip the download and use Load unpacked.
- **Chrome refuses the ZIP.** Chrome never installs a theme ZIP directly.
  Unzip it and pick the folder that holds `manifest.json`.
- **The Firefox theme lost its wallpaper.** Firefox themes cannot set a New
  Tab image, so the package drops it and says so.
- **"Couldn't copy to the clipboard."** The page lacks clipboard permission.
  Use Export manifest.json instead.

## Next

- [Publish and hand off](/themes/publish)
- [Firefox preview](/themes/firefox-preview)
- [Import a theme](/themes/import)
- [Publish overview](/publish/overview)