UserCSS

UserCSS authors, please refer to the Writing UserCSS page for more details.

Contents

• What is UserCSS?
• How do I install UserCSS?
• How do I customize UserCSS?
• Awesome! Now I want to create my own

What is UserCSS?

UserCSS is essentially a CSS stylesheet with some extra data added to the beginning. We add a .user.css extension so you know it's different.

So what's all the hype about it?

• Self-hosting: UserCSS styles help to preserve your privacy. A UserCSS style can be hosted and installed from anywhere, even your own drive. That way you can prevent userstyle repository web sites tracking you. We emphasize can preserve as it is dependent on where the UserCSS is hosted.
• User-customizable variables: These style settings (including colorpicker) can be live-switched, are maintained during updates and can be set back to defaults separately.
• Preprocessor: Besides standard CSS, these preprocessors are supported: LESS, Stylus-lang and the USO-format. Furthermore you can utilize whatever you want by using live-reload and your own external editor.

How do I install UserCSS?

Userstyle manager

First, you need a userstyle manager that supports installing UserCSS.

Currently these two extensions support UserCSS, but the UserCSS is not standardized, so a userstyle may work in one, but not the other.

• Stylus for Firefox , Chrome or Opera (recommended).
• xStyle for Firefox or Chrome .

We do work very hard to make sure Stylus supports all existing standards of UserCSS; we're also trying to improve that standard.

UserCSS file

Now we need to find a style to install.

• All UserCSS files have a .user.css ending.
• Or if you find a style in a blog post or comment, look for /* ==UserStyle== at the top of the style.

Install a file

To install a file, open the file within the browser. The file can be hosted anywhere on the web, or on your local drive.

For example, to add a Quora.com Dark theme, go to Quora Dark installation instructions (you don't need to be logged in), then click the "Install the usercss" link.

You could also open the .user.css file directly if you know the url.

Once the raw quora-dark.user.css file is open in the browser, Stylus will open a new tab showing some basic information & options:

• Click on:
  • "Install style" to initially install the style.
  • The button will be labeled "Reinstall style" if the style is already installed.
  • Or, it'll be labeled as "Update style" if the style is already installed, and it needs to be updated.
• The "Check for updates" checkbox.
  • Check this box if you want the style to automatically update.
  • If the UserCSS includes a location, you'll see it below the checkbox label. This is the url where the style manager will look to see if the UserCss needs to be updated.
  • If no location is set, the manager will check for updates from where the UserCSS was installed by you.
  • Uncheck this box if you don't want automatic updates.
• Review the remaining information as desired.

Once installed, you will be redirected to Stylus' editor page with the newly installed/updated UserCSS loaded. Close this if you don't want or need to modify the style.

Install from a comment or blog

It is also possible to add a UserCSS style from any text.

Given this simple example:

/* ==UserStyle==
@name         Example UserCSS style
@namespace    github.com/openstyles/stylus
@version      1.0.0
@license      unlicense
@preprocessor default
@var color link-color "Link Color" red
==/UserStyle== */

@-moz-document domain("example.com") {
  a {
    color: var(--link-color);
  }
}

Do the following:

• Select all the text within the above block, starting with /* ==UserStyle== and ending with the last } (closing curly bracket).

• Now, copy the selection - right click & select copy, or use Ctrl or ⌘ + c.

• Open the editor:

  • From the Popup, click on the "this URL" portion of the link under "Write style for:"

    

    If you see a "Mozilla Format" section in the side bar, the editor is in the wrong mode! To fix this, open the editor from the manager; Click the "Back to manage" button, then read the next step on how to open the editor from the manager page.

    

  • From the Manager, make sure the "as UserCSS" checkbox is checked, then click the "Write new style" button

    

• Click in the main editor area so that the cursor is on any line with a line number (i.e., not in the "Applies to" select or input area).

  

• Now select all of the content - right click & Select all, or use Ctrl or ⌘ + a.

• Paste in the UserCSS that was copied before - right click on the selection & paste, or use Ctrl or ⌘ + v.

• You might see some red x's and yellow warning signs show up next to the line number, don't worry; this is the css being checked for errors, and the default selected CSSLint may not recognize the format being used.

  

• Click the "Save" button in the side bar, and close the editor.

• You're done!

How do I customize UserCSS?

To configure a UserCSS, go to the Manager page (or the Popup) and click on the "Configure" icon () next to the style name to open the dialog.

The dialog will show all the available customizable options.

In this example, all types of customizable elements are shown.

In the footer of the popup, set the "on change" checkbox to immediately apply any updates to the UserCSS. So if the style is open in a separate window, you can see the applied customization while the values are being altered.

• Color setting (Link color) - Click on the color swatch to open the Colorpicker.
• Option Select (Position) - Click on the select box to modify the available choices.
• Checkbox (Checkbox) - Click on the switch to toggle the choice.
• Text Input (Font Family) - Click to focus on the input and enter the desired choice.
• Number Input (Height (px)) - Use the input to set a numeric value.
  • Type in the number, or use the up and down arrow keys to adjust the value.
  • If there is a limited range set on this setting, the value will automatically adjust.
• Range Input (Opacity) - Use the range slider to adjust the value.
  • After focusing on the slider handle, the arrow keys may be used to adjust the value.
  • The value to the left of the slider shows the current setting; this value may contain the unit of measure, e.g. 10px or 50%.

After making the desired changes and click on:

• "Save" to save your current selections.
• "Reset" to reset the configuration to the default settings.
• "Close" to close the popup.

Awesome! Now I want to create my own

Before we jump into creating UserCSS styles. Make sure you learn or already know some of the following:

• Basic CSS .
• Advanced CSS (optional):
  • CSS variables (Covered in the Basic CSS course above)
  • LESS .
  • Stylus language .

Then when you're ready, read over our documentation for Writing styles and Writing UserCSS.