Indie game storeFree gamesFun gamesHorror games
Game developmentAssetsComics
SalesBundles

Uploading HTML5 games

itch.io supports uploading HTML games in addition to downloadable, Flash, Unity, and Java games. In order to get started just head over to the New Game or Edit Game page and pick “HTML Game” from the Kind Of Game list.

Getting started

itch.io supports HTML5 games by embedding an iframe pointing to your game on itch.io’s own game page. All of your game’s assets are hosted by us so you don’t need to worry about uploading your game anywhere else. All you need to do is provide the dimensions of your game along with the game’s files. There are two ways to upload an HTML5 game:

  • Upload a ZIP file that contains all the games files, including an index.html file that will be your games entry point.
  • Upload a single HTML file that contains your entire game.

ZIP File

We recommend uploading a ZIP file when your game is comprised of many different files.

The ZIP file must contain a file called index.html, this is what people will see when they go to play your game. The ZIP file should include all the files necessary to run your game. File names are case sensitive.

Your ZIP file can contain any kind of file you need for your game. Make sure to use relative paths when developing your game to ensure assets are loaded correctly. If you make a mistake or release a new version of your game feel free to upload a new ZIP file and delete the old one.

HTML File

For smaller games, you can also directly upload an .html file.

The entire game must be in a single HTML file. Your game will not be able to reference any other files you've uploaded on itch.io project edit page. If you need multiple files then we recommend uploading a ZIP file instead.

Viewing Your Game

After setting your game’s dimensions and uploading the ZIP file you can preview your game on itch.io. Upon first loading the game page, itch.io will take a moment to process the archive.

Meanwhile you are free to customize your game page as you would with any other game on itch.io.

Can I take payments with my HTML5 game?

Currently all HTML5 games on itch.io are set up to only take payments as donations. However, it’s possible to sell access to your game by setting its “Kind of Game” to “Downloadable”. If you'd like itch.io to support purchasable HTML5 games then you should get in touch.

ZIP file requirements

There are a couple of requirements for ZIP files in place to prevent abuse and to ensure a suitable experience for people running your project in their browser.

  • The ZIP file should not contain more than 500 individual files after extraction.
  • The maximum length of a file name including path should not be greater than 240 characters long.
  • The size of all the extracted content should not be greater than 1GB.
  • The size any single extracted file should not be greater than 100MB.
  • There are less than 3000 files in the zip file

If your game does not meet the requirements please consider distributing your game as downloadable instead. Very large HTML5 games tend to be a poorer experience compared to the equivalent downloadable in respect to loading time and performance.

Feel free to contact us if you think these limits aren’t appropriate for your project and we can help you get set up.

Customizing how your game is embedded

From your project’s edit page you can customize how your HTML5 game is embedded into its itch.io page.

  • Click to Play — By default your project will require a click to start. This will ensure your game doesn’t slow the viewer’s browser when the itch.io page initially loads. If you have a lightweight project, you can disable Click to play and your project will start when the page loads. Keep in mind audio may be muted on some browsers when using auto-start.
  • Fullscreen Button — We can automatically generate a fullscreen button for your project if the engine you are using doesn’t automatically provide one.
  • Viewport Dimensions — You have a few options for setting the size of your viewport. The simplest way is to manually provide the dimensions. For some game engines, we support automatically detecting the dimensions. If you'd like your game to always take up the maximum size of the screen, you can use Click to launch in fullscreen.
  • Scrollbars — Some projects are designed to be larger than the size of their viewport. Enabling scrollbars will allow viewers to scroll within the iframe. They are hidden by default.

Visual customization

For projects that use Click to play, you can customize the what the viewport looks like before the game is launched. You can find these options on the project’s theme editor.

  • Background Image — A image that takes up the size of the viewport that sits behind the Play button.
  • Gradient — A gradient color can be overlayed on the viewport to help you match the colorscheme of your page.

Support for Mobile HTML5 Games

Many HTML5 game engines support playing games through a mobile web browser. If you know your project functions in a mobile browser then you can select the Mobile Friendly option in the embed settings for you project.

When your itch.io page is loaded on a mobile device, it will use Click to launch in fullscreen mode regardless of how you've configured your embed for desktop computers. This will ensure itch.io’s user interface does not interrupt your application, along with preventing an autostarting game from unexpectedly consuming resources.

If you haven’t enabled Mobile Friendly then a warning will be displayed to the viewer that the game may not work, but they can still attempt to start it.

Game Engine Detection

When you upload your HTML5 game we'll scan the files to detect the game engine used automatically. This can help get your project listed in our browse pages. Here are some examples of HTML5 games using specific engines.

If you think we're missing a engine you can suggest a new one.