Your website
Custom themes: upload your own design and update it with new versions
A custom theme is your own design for an Eyivo website: its layout, page templates and styles. Start from the sample theme, edit it, then upload it under Custom themes in the Eyivo panel. Each upload is checked before it can be used, and uploading never changes a live website.
Reviewed · English guide
Start from the sample theme
- Choose Download sample theme under Custom themes in the Eyivo panel, or download the repository from github.com/eyivo/eyivo-sample-theme.
- The theme is the sample-theme folder. Edit only the files inside it: theme.json, the layouts, page types, components, styles, translations, demo content and preview screenshots.
- Everything else in the repository is documentation and an optional helper tool. Don't put those files in your theme.
- The optional helper checks your theme before you upload it: run php bin/eyivo-theme validate sample-theme in the repository folder. It needs PHP 8.1 or later. You don't need it to upload; Eyivo checks every upload and lists any problems.
- The Theme API documentation explains every file and setting a theme can use.
Upload a new theme
- Zip the sample-theme folder. Zipping the folder itself or only its contents both work.
- In the Eyivo panel, open Custom themes, choose the zip under Upload a new theme and select Upload and validate.
- Each upload there creates a new theme. Eyivo gives it its own ID, so the folder name in your zip and the key in theme.json don't matter.
- The theme takes its name from name in theme.json. You can rename it later on the theme's page; only you see this name.
- If the upload fails, the panel lists each problem with the file it's in. Fix them and upload again.
What a version's status means
- Checking package: Eyivo is unpacking the zip and checking its files, templates and demo content.
- Pending review: the package is valid and the automatic review is running. A version without scripts is approved within moments; one with scripts usually takes a few minutes. You can't preview or use it yet.
- Approved: you can preview the version and use it on your websites.
- Rejected: the review found a problem. The version's page lists each finding with its file and line. Fix them, raise the version number and upload a new version.
- Blocked: a version that was approved was later found to break the rules. Websites that use it keep the theme, but its scripts stop running, and it can't be used on other websites. Upload a fixed version.
- Retired: you retired the version. It stays in the list but can't be used again.
- You get an email when a version with scripts is approved, rejected or blocked.
Update a theme with a new version
- Raise version in theme.json, for example from 1.0.0 to 1.1.0. Each version of a theme must have its own number.
- Open the theme under Custom themes and use Upload a new version. The zip always becomes a version of that theme.
- Uploading from the main Custom themes page would create a separate theme instead.
- The theme's page lists every version, with what changed compared with the one before.
Switch your websites to a new version
- On the theme's page, choose the new version and Use as draft for a website.
- Check the draft, then publish it from the website's Design page.
- Do this for each website that uses the theme. Websites you don't switch keep their current version.
- The previous version stays available for 30 days, so you can switch back if something looks wrong.
Retire or delete old versions
- Retire a version when no website uses it as its current version, draft or rollback. It stays in the list but can't be used again.
- A version that was never installed on a website can be deleted completely.
Themes with their own scripts
- Theme developers can add JavaScript files for menus, sliders, tabs and similar features. The Theme API page explains the rules for writing them.
- When you upload a theme with scripts, you confirm that you are responsible for them. Each version's scripts are checked for readable code and unsafe patterns, and sent to an AI service for a security review.
- Approved scripts run only on websites you own.
- To stop a theme's scripts on one website without changing theme, open the website's Design page and use Run theme scripts. The theme keeps working without them.
- Visitors can report a website from its Report this website page. If several visitors report one of your websites, its theme scripts are switched off there while the version is checked again: they come back if it passes, and the version is blocked if it doesn't.
- Scripts never replace or hide Eyivo features such as forms, human verification, the consent banner, the Eyivo badge or the owner bar.