Skip to content
iKeySnail provides fully-configurable hardware keyboard functionalities for web browsing on iOS (iPadOS)
JavaScript HTML Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
package
src
.gitignore
README.md
package.json
webpack.config.js

README.md

iKeySnail

iKeySnail provides fully-configurable hardware keyboard functionalities for web browsing on iOS (iPadOS).

The aim of this project is to provide { Vimium, Vimperator, Surfingkeys, KeySnail } for iOS. Currently, iKeySnail supports

  • Hardware keyboard supported web browsing
    • Emacs-like keybindings/functionalities
      • e.g., Ctrl-Space to set mark, Meta-w to copy the selected region, Ctrl-y to yank (paste) the clipboard text
    • Vim-like keybindings/functionalities
      • e.g., j/k/h/l/g/G to quickly scroll web pages
  • Link-hints (Hit-a-hint)
    • For clicking links without touching your iOS device screen
    • hints
  • Vertical tabs
    • We do support vertical tabs in iOS!
    • Setting config.TAB_VERTICAL = true makes tab orientations vertical
    • vtabs
  • Omnibar support
    • Work-in-progress, but we do support omnibar. By default, pressing o opens your bookmarks.
    • omnibar

Installation

You need JSBox (https://docs.xteko.com/#/en/) to run iKeySnail. After installing the JSBox, access either of

from iOS Safari. Then JSBox will install iKeySnail.

You can also manually download the repository as a zip file and install it in JSBox.

Usage

See strings/settings.js for available shortcuts.

Customization

Edit strings/settings.js.

Defining / Customizing Keymap

We have four types of mode for key bindings.

  1. all-mode, whose keymaps are always active.
  2. view-mode, whose keymaps are active only if the cursor isn't on editable elements (akin to vim's normal mode).
  3. rich-mode, whose keymaps are active only if the cursor is on rich text editors (such as CodeMirror, Ace, Scrapbox, and contenteditable).
  4. edit-mode, whose keymaps are active only if the cursor is on input or textarea.

In each keymap, you can define a key's functionality in two ways:

  1. Remapping to different key (e.g., "ctrl-s": "meta-f"), and
  2. Invoke a JavaScript function (e.g., "ctrl-y": () => keysnail.paste()).

Defining a site

You can also define a site configuration in your settings.js. Configuration consists of

  • keymap -> keymap
  • style -> user css
  • alias -> alias
  • url -> url.

Examples are follows.

config.sites.push({
    alias: "Google",
    url: "https://www.google.com"
  });

  const GDOCS_KEYMAP = {
    rich: {
      "meta-f": keysnail.marked("alt-ArrowRight"),
      "meta-b": keysnail.marked("alt-ArrowLeft"),
      "meta-d": keysnail.marked("alt-Delete"),
      "ctrl-_": "ctrl-z",
      "ctrl-z": "meta-z",
      "ctrl-s": "ctrl-f"
    }
  };

  config.sites.push({
    alias: "Google Docs",
    url: "https://docs.google.com/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "Google Docs (Slide)",
    url: "https://docs.google.com/presentation/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "OverLeaf",
    url: "https://www.overleaf.com/project/",
    style: `
.toolbar { font-size: small !important; }
.entity { font-size: small !important; }
`
  });

  config.sites.push({
    alias: "Scrapbox",
    url: "https://scrapbox.io/",
    keymap: {
      rich: {
        "meta-f": keysnail.marked("alt-ArrowRight"),
        "meta-b": keysnail.marked("alt-ArrowLeft"),
        "ctrl-i": "ctrl-i",
        "ctrl-t": "ctrl-t"
      }
    },
    style: `
#editor {
  caret-color: transparent !important;
}
`
  });

Gifs

Omnibar

omnibar-mov

Link hints

linkhints-mov

Acknowledgements

Parts of iKeySnail are inspired by previous wonderful works (thanks to).

You can’t perform that action at this time.