userstyles.org - Coding user styles

Writing styles requires a working knowledge of CSS. If you don't know CSS, there are many tutorials available online. It may also be helpful to inspect the source of other styles to see how things work.

To post new styles on userstyles.org, you will have to create a user account. Once logged in, you'll see a Create new style link on your user home page.

CSS support

Stylish styles are written entirely in CSS. The CSS features supported are determined by the browser you're using. Consult the CSS specifications for information on each feature, but also check which browsers support it.

Format of user style code

User style code must be posted as plain CSS. No HTML tags, no Greasemonkey scripts, nothing else.

The "native" format for specifying which URLs the style should apply to is the Mozilla @-moz-document format. While the site knows how to convert styles for use in Chrome or Greasemonkey, it requires the source format use @-moz-document.

Making user styles specific to a site

To make a user style only apply to certain sites, you can use @-moz-document rules. The rules types available are url, url-prefix, and domain.

@-moz-document domain('images.example.com'), url-prefix('http://example.com/images') {
	/* 
		the code in here only apply to:
			-pages on the domain images.example.com
			-pages whose URLs start with http://example.com/images
	*/
}

Rather than writing this each time, you can get Stylish to automatically generate code for a certain site. When you're on the site, click the Stylish icon, click Write new style, then choose For this URL or For example.com.

When using these rules, you should keep in mind the same site can sometimes be accessed in many ways - http://example.com, http://www.example.com, https://example.com, http://example.co.uk.

There is no way to put wildcards in the values, and there is no way to select everything except a certain site.

Limits on user styles

Styles are limited in a few ways:

Creating selectors for sites

Writing user styles is different than writing CSS when developing a site because you're not in control of the HTML. You will have to write selectors that use what's available in the document. This usually means using the available classes and IDs.

Some sites have very complicated layouts that involve tables or few classes or IDs. To style this kind of site, you'll have to make use of fancy selectors like nth-child.

Specificity is an important concept to understand when dealing with selectors.

Overriding sites' existing styles

Often rather than adding new styles, you need to override existing styles. To ensure that your style will override the site's style, add !important at the end of every value.

#example { color: blue !important }

Making cross-browser compatible styles

Firefox is used by the majority of userstyles.org users. Chrome comes in second. When using vendor-prefixed rules or values, keep in mind other browsers. If you know that a style won't work for certain browsers, making a note of it in the style's description to avoid getting bad ratings.

Stylish doesn't add any CSS capabilities to the browsers. If a browser doesn't support a CSS feature, then it won't work through Stylish.

Making user styles for a Mozilla-based program's user interface

Mozilla-based user interfaces are written in XUL, which is a flavour of XML. You can write the same kind of code to affect the user interface as you would any other page. Since the source is more difficult to access, tools such as DOM Inspector are useful.

To limit a style to the program (and not affect web sites), you can use the -moz-document rule to only affect chrome protocol pages. The chrome protocol is used for all the interface UI.

@-moz-document url-prefix('chrome://') {
	/*
		the code in here only apply to the program's user interface, not web sites
	*/
}

There is currently no way to make user styles for a non-Mozilla-based program's user interface.

Namespaces

XML namespaces are what allow different flavours of XML to have the same elements and attributes but mean different things. One example is label - both HTML and XUL define elements named label, but they're different things.

CSS understands XML namespaces. You can define namespaces for your styles.

@namespace html url(http://www.w3.org/1999/xhtml);
@namespace xul url(http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul);

html|label { /* this will affect HTML labels */ }
xul|label { /* this will affect XUL labels */ }
label { /* this will affect labels of any type */ }

You can define a certain namespace as the default to use for all element selectors. Stylish's editor's Insert drop down includes options to insert these codes.

@namespace url(http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul);

label { /* this will affect only XUL labels */ }

Replacing images in <img> tags

While replacing background images is easy with CSS, replacing images created with <img> tags is not. You need to do the following trick to switch <img> tag images.

#yourSelectorHere {
	height: 0 !important;
	width: 0 !important;
	/* these numbers match the new image's dimensions */
	padding-left: 125px !important;
	padding-top: 25px !important;
	background: url(http://example.com/your/image/here) no-repeat !important;
}

Embedding images in user styles

If your styles require images, it's often useful to embed the images inside the styles. Doing so eliminates the delay in downloading the image from a server and makes it so that anyone can just install the file without placing additional images on their machines.

data URIs can be used to embed images in styles. These URIs include encoded data about the image, so are very long. To generate data URIs, from the Stylish edit dialog, choose Insert, Data URI, then choose the file you wish to embed.

Getting a better editor inside Stylish

You can use It's All Text! to integrate Stylish's code editor with an external editor of your choice.

Sharing user styles

The best way to share user styles is to post them to this site. Doing this makes it easy for others to find and install your styles and lets them easily receive updates should you change your style.

An alternate way is to provide put your code in a CSS file and host it somewhere. This will still allow for updates, but there won't be an easy button for users to click to install, and they will have to provide a name for the style themselves.

A final way is to simply provide the code and make users copy and paste it into Stylish. No updates are possible this way.

Deleting user styles off of userstyles.org

To delete a style off the site, go to the edit screen, then click the link for deleting. There is no way to truly delete a style; rather, the style no longer shows up in search results, and a large warning is displayed to anyone accessing it directly. This is so that previous users of the style know what happened to it. Please do not "blank out" the style instead of deleting.

Style settings

Style settings let you give users options for installing your style. The easiest way to explain is with an example.

Here is the code:

* {
	color: /*[[mycolor]]*/;
	font-face: /*[[myfont]]*/;
}

Here is what you define as the settings

This will show the user this UI:

Choose a color Red
Green
Blue
Choose a font Serif
Sans-serif
Ugly

If the user chose "Red" and "Sans-serif", the would receive this code:

* {
	color: red;
	font-face: Times New Roman, serif;
}

You're not limited to single values with this - you can turn entire blocks of code on or off with style settings.

Styles with style settings are not updatable by Stylish.

Linking in style descriptions

You can create links in three ways: