How to use "Userscripts" an extension that allows custom JS and CSS in Safari on iOS

2023-08-27 2023-12-12

Here's how to use "Userscripts," an extension that allows you to run arbitrary JS and CSS in Safari on iPhone and iPad.

For example, if you create a JS like this:

$("body").css("background", "linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%)"); //Green gradient

When executed on google.co.jp, it will be reflected like this.

Userscripts Google test

You can do various things, not just CSS changes, but also automatically fill out forms, click buttons, and more.

The app is here.

Userscripts

Justin WasackFreeposted withAppReach

Create a folder in iCloud
App settings and permissions
Create a JS file
Execute in Safari
How to write code
- How to create CSS

Create a folder in iCloud

First, create a folder on iCloud Drive.

This time, I created a folder named "test".

iCloud Driveにtestフォルダを作成

By placing it on iCloud instead of locally, it's convenient because you can edit on a PC and check on an iPhone, or share it between devices.

App settings and permissions

Launch Userscripts and set the folder you just created from "Set Userscripts Directory".

Userscripts iOS

Then, go to iPhone's "Settings > Safari > Extensions > Userscripts" and turn the switch on.

Set "All Websites" below to "Allow" or "Ask".

Userscripts iOS 拡張機能許可

Create a JS file

As a test, create a JS file with the following code.

// ==UserScript==
// @name        test
// @description This is a test of the JS file.
// @include     https://www.google.co.jp/*
// @require     https://code.jquery.com/jquery-3.7.0.min.js
// ==/UserScript==

$("body").css("background", "linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%)"); //Green gradient

For more details on the code, please see below.

Save it as "test.js" in the folder you created earlier.

iCloud Driveにtest.jsを作成

If you are creating code on an iPhone or iPad (without using a Mac), you will need a separate text editor app.

Please use one of those to create the JS file.

Execute in Safari

In Safari, open the website where you want to execute the JS (google.co.jp in this case).

Tap "Userscripts" from the "Aa" in the address bar.

Safari Userscripts

The first time, a pop-up will appear, so tap **"Allow for One Day" or "Always Allow"** as you prefer.

Userscripts アクセスを求めていますポップアップ

Then, a list of files that can be executed on this website will be displayed.

Userscripts Safari

It will be reflected when you refresh the page.

Userscripts Google カスタマイズ

How to write code

To execute JS or CSS with Userscripts, you need meta information like the following at the beginning of your code.

// ==UserScript==
// @name        test
// @description JS test
// @include     https://www.google.co.jp/*
// @require     https://code.jquery.com/jquery-3.7.0.min.js
// ==/UserScript==

$("body").css("background", "linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%)"); //Green gradient

At first, I struggled because I didn't know this...

Roughly, how to write meta information

@name

Title (Required) (Choose any name you like)

@match

Specify the URL you want to execute with a match pattern (Either @match or @include is required)

Examples of writing

(Executable on all sites)

*://*/*

(Executable on subdomains of a specific domain)

*://*.knis.jp/

(Executable under a specific directory of a specific site)

*://blog.knis.jp/userscripts/*

@include

Specify the URL you want to execute (Either @match or @include is required)

Examples of writing

(Executable on all sites)

*://*/*

(Executable on domains ending with "google.co.jp" for http or https)

http*://*google.co.jp/*

@exclude

Specify URLs to exclude (writing method is the same as @include)

@description

Description

@require

Specify the external file you want to load by URL.
You can use jQuery by specifying its CDN.

For the difference in how to write @match and @include, the article below is easy to understand.

@match Match Pattern Writing - Sleepy Gamer's Memo

The value of @name does not have to be the same as the file name. Please set it freely.

For other meta information, please refer to the Userscripts official documentation.

How to create CSS

CSS can be executed by setting meta information like this.

/* ==UserStyle==
@name        test CSS
@description CSS test
@include     https://www.google.co.jp/*
==/UserStyle== */

body {
	background: linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%);
}

Save this as a .css file, such as "style.css".

By the way, in my case

At first, the CSS file extension was not displayed, and Userscripts did not recognize it.

iCloud Drive .css 拡張子表示されない

In such cases, checking "Show All Extensions" from the top right menu > View Options resolved the issue.

iCloud Drive すべての拡張子を表示

Comments

#001
2023-10-11
Anonymous

Hello. Thank you for the very useful information. If you don't mind, could you please tell me about the CSS creation method described at the end? Should the file itself be saved as .js or .css?

Also, regarding @name, is it okay if it's not the same as the saved file name?

I'm more familiar with CSS, so I wanted to try it and had these questions.

(The test.js described worked fine in Chrome. Thank you.)
#002
2023-10-12
Owner

Please save CSS as .css.

Regarding @name, it's okay if it's not the same as the file name.

I received your feedback and have reflected it in the article.

Thank you for your comment!
#003
2023-12-12
Anonymous

Excuse me for a basic question. It says to create JS code, but do I need a separate text editor app?
#004
2023-12-12
Owner

My apologies, I wrote this assuming editing on a Mac...

That's right, if you want to complete it solely on an iPhone or iPad, you'll need to install a separate text editor app to edit it.

I don't have any specific app recommendations, so please try searching for one.

I received your feedback and have reflected it in the article.

Thank you for your comment!