itch.io supports uploading HTML games for play directly in the browser. In order for your game to function it must be implemented using web technologies such as HTML, JavaScript, and CSS. Many modern game engines support exporting to HTML & Javascript, which will allow your players to run your game directly in their browser without separate downloads or installs.
Note: Although in this guide we mention games specifically, you can upload any kind of HTML/JavaScript/CSS project on itch.io.
Quickstart: Head over to New Game or edit an existing page, pick “HTML Game” from the Kind Of Game list, then upload your game packaged as a ZIP file.
itch.io supports running HTML/JavaScript/CSS projects directly in the browser by embedding
an iframe
pointing to your uploaded code on your itch.io project page.
All of your game’s assets are hosted by us so you don’t need to worry about
uploading files anywhere else. There are two ways to upload an HTML5 game:
index.html
file that will be your game’s entry point.If your game is more than a single file, it must be uploaded as a ZIP file.
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.
For simple projects that are self contained in a single .html
file, you
directly upload the file without zipping it.
Your page will not be able to reference any other files you've uploaded on itch.io page. If you need multiple files then you must upload a ZIP file instead.
On your project’s edit page, after uploading an appropriate file to be embedded, you will see a new section called Embed options where you can configure how your code will be embedded.
There are two ways your game can be displayed:
Here are some of the other options we provide for customizing your embed:
iframe
. They are hidden by default.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.
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.
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:
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.
Why do we have limits? Although many game engines allow you to export anything as an HTML5 project, often you need to consider what the user experience of playing the game will be like. You can think of an HTML5 project like a website: many of the same performance optimization recommendations still apply. We have these default limits to encourage developers to consider how their games are distributed, especially since it’s so easy these days to drop in prefab resources from asset-stores that significantly increase the download size for the game.
Feel free to contact us if you think these limits aren’t appropriate for your project and we can see what we can do .
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.
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 your 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 auto-starting 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.
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.
Here are some common issues people run into when uploading their project. If you're about to upload something, or are having an issue, read through the list first.
.rar
,.tar.gz
, and .7z
are not supported). Uploading multiple files individually to the itch.io website will not work either, you must combine all necessary files into a ZIP file. Note that if your project is a single HTML file, then you can upload that directly and skip ZIPing it./
) instead of a specific file. Due to our security settings, our system will return a 403
error instead of the more commonly seen 404
. (In Chrome you may see net::ERR_ABORTED 403
)./
. You must use relative paths to access other files you have provided in your project.net::ERR_ABORTED 403
error in Chrome. If you have a file named Hello.png
, you must reference it as Hello.png
, things like hello.png
and HELLO.png
will not work because the case does not match.When exporting your game for itch.io we recommend using a template or markup that allows for your game’s canvas to adjust to the size of the window is is placed in. When using a fullscreen button the viewport size will dynamically adjust to the size of the viewer’s screen. Additionally, when running an HTML5 game on a mobile device, the viewport will have a dynamic aspect ratio and resolution matching the user’s device.
Here are some recommend resources:
If you have any other recommended resources or tips for configuration please send them to support.
Some game engines will pre-compress assets as part of their build process. In order for these assets to download correctly, often the webserver will have to detect these and apply the appropriate headers for the particular file.
content-encoding
header to gzip
. The content-type
header of the file will detected and set by the extension, removing .gz
if necessary..br
then we'll assume that the content is Brotli compressed and the content-encoding
will bet set to br
. The The content-type
header of the file will then be detected and set by the extension, after removing the .br
. (Note: Brotli encoding can not be detected like gzip, so we must depend on the .br
extension). This approach is commonly used by Unity 2020 WebGL export.In order to reduce bandwidth and decrease loading times, itch.io’s CDN will automatically apply GZIP compression to the following file types if they are provided uncompressed.
File extensions:
html
js
css
svg
wasm
wav
glb
pck
If we aren’t able to match by extension, if we see the following content type on a file we will also attempt to compress it:
application/x-javascript
application/javascript
text/javascript
text/css
text/html
application/xml
application/json
image/svg+xml
Follow itch.io on Twitter, Facebook or Join our Discord for new games and site updates.