Skip to content
Get packs

Guide · Open source

How to use Ratchet: set up files and build mobile-style pages

Updated · written with AI from the project's own documentation and checked against our catalogue data

Ratchet is an open-source front-end toolkit of ready-made HTML, CSS and JavaScript components for building mobile app interfaces in a browser. This guide is for developers and designers who want to prototype how a web app looks and feels on a phone. By the end you will know how to get the files, what the download contains, how to run the documentation locally, and how to avoid the most common problems.

Ratchettwbs/ratchet · ★ 14.7k · MIT

Quick start

  1. 1Get the files. Clone the repository with git clone or download the bundled CSS and JS from the project.
  2. 2Pick a stable version. Use the master branch only for development. For a stable copy, choose a tagged release.
  3. 3Include the core CSS and JS. Link css/ratchet.min.css and js/ratchet.min.js in your HTML page, or the non-minified versions while debugging.
  4. 4Add a platform theme if needed. Optionally include the Android or iOS theme CSS to match a phone platform.
  5. 5Serve the page locally. Run a local server such as python -m SimpleHTTPServer so XHR page loads work instead of opening the file directly.
  6. 6Test touch behaviour. Check the interface on a phone, or enable touch event emulation in Chrome for desktop testing.

What is Ratchet and who is it for?

Ratchet ships as compiled CSS and JavaScript files, with optional Android and iOS themes. Developers use it to prototype how a web app would look and feel on a phone.

It suits developers prototyping a mobile-style web interface with plain HTML, CSS and JS, designers who want to see mobile UI components in a browser, and teams maintaining an existing Ratchet 1.x or 2.x project.

  • Not a fit for framework-based setups such as React or Vue, since the README describes only plain HTML, CSS and JS files.
  • Not a native iOS or Android app builder; it builds web pages instead.

Get the Ratchet files

You can clone the repository or download the bundled CSS and JS. The README lists no prerequisites for this method. The master branch is the active, unstable development branch, so for a stable copy use the tagged downloads.

  • Clone the repo with the command below.
  • Or download the bundled CSS and JS from the project's download link.
  • For a stable copy, pick a release from the tagged downloads page.
git clone https://github.com/twbs/ratchet.git

Understand the file layout

The download includes compiled and minified variations. Files named ratchet.* are compiled CSS and JS, and ratchet.min.* are the minified versions. The Ratchicon fonts and the optional Android and iOS platform themes are included.

  • css/ratchet.css and css/ratchet.min.css for the core styles.
  • css/ratchet-theme-android.css and css/ratchet-theme-ios.css for the optional platform themes.
  • js/ratchet.js and js/ratchet.min.js for the components' JavaScript.
  • fonts/ holds the Ratchicon font files in eot, svg, ttf and woff formats.
ratchet/ ├── css/ │ ├── ratchet.css │ ├── ratchet.min.css │ ├── ratchet-theme-android.css │ ├── ratchet-theme-android.min.css │ ├── ratchet-theme-ios.css │ └── ratchet-theme-ios.min.css ├── js/ │ ├── ratchet.js │ └── ratchet.min.js └── fonts/ ├── ratchicons.eot ├── ratchicons.svg ├── ratchicons.ttf └── ratchicons.woff

Run the Ratchet documentation locally

The documentation is built with Jekyll and hosted on GitHub Pages, and it can also be run on your own machine. The README says Jekyll needs v3.0.x. It also asks you to install the Rouge syntax highlighter.

  • Install Jekyll if you do not have it (the README requires v3.0.x). Windows users can follow the unofficial guide linked in the README.
  • Install Rouge with gem install rouge.
  • From the root ratchet directory, run jekyll serve.
  • Open http://localhost:4000 in your browser.
gem install rouge jekyll serve

Fix common problems with touch and local files

Ratchet is designed to respond to touch events from a mobile device, so clicks on a desktop may not behave as expected. The README suggests enabling touch event emulation in Chrome or loading a library such as fingerblast.js from desktop devices only.

Ratchet loads extra pages with XHR requests. Modern browsers block these when a file is opened directly with the file:// protocol, so Ratchet will not work from a double-click. Serve the files from a local server instead. The README suggests a simple Python server.

  • Script tags will not run on pages loaded with push.js; use document-level event delegation to attach handlers on other pages.
  • Use a local server rather than opening the HTML file directly.
python -m SimpleHTTPServer <port>

Know the versioning and where to get help

Ratchet follows Semantic Versioning: breaking changes bump the major number, backward-compatible additions bump the minor number, and bug fixes bump the patch. For questions, the README points to a Google group and a Twitter account. Bugs should be filed as GitHub issues following the contributor guidelines.

What people use it for

  • Prototyping how a web app screen would look on a phone before building the real back end.
  • Showing mobile UI components to a client or team in a desktop browser.
  • Maintaining or extending an existing Ratchet 1.x or 2.x project.
  • Learning how mobile-style navigation and components are structured in plain HTML, CSS and JS.

Frequently asked questions

Is Ratchet free to use?

Yes. Ratchet is licensed under the MIT License, as stated in the README. Check the license file in the repository for the full terms.

How do I install Ratchet?

The README gives two options: clone the repository with git clone https://github.com/twbs/ratchet.git, or download the bundled CSS and JS. No prerequisites are listed for these steps.

Does Ratchet work with React or Vue?

The README describes only plain HTML, CSS and JS files, so Ratchet is not presented as a React or Vue setup. Choose a framework-based toolkit if that is your requirement.

Why does Ratchet not work when I open the HTML file directly?

Ratchet fetches extra pages with XHR requests, and modern browsers block these under the file:// protocol. Serve the files from a local server, such as python -m SimpleHTTPServer, to fix this.

Why don't clicks work on my desktop browser?

Ratchet is built to respond to touch events. You can enable touch event emulation in Chrome or use a library such as fingerblast.js on desktop only.

What are the alternatives to Ratchet?

Comparable projects named in our analysis include Framework7, Onsen UI and Ionic Framework. Compare their setup and maintenance status against your project before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ratchet suits developers and designers who want a simple, plain HTML, CSS and JS way to prototype a phone-style web interface, and teams already on Ratchet 1.x or 2.x. Pick a different tool if you need React or Vue, a native app, or a toolkit with active, recent updates, and check the repository's latest activity before relying on it.

Install options & downloads