Wikipedia:TemplateStyles

This page documents an English Wikipedia editing guideline.

Editors should generally follow it, though exceptions may apply. Substantive edits to this page should reflect consensus.

Shortcuts

TemplateStyles enable the use of custom CSS pages to style content without requiring an interface administrator to edit sitewide CSS. This feature allows editors to create and maintain template-specific styles, improving flexibility and avoiding the need for global CSS changes, like MediaWiki:Common.css, that could have unintended effects elsewhere on the site.

TemplateStyles make it easier to ensure templates display consistently across different skins (for example, Vector) when sitewide CSS rules would otherwise interfere.

TemplateStyles work on all types of pages, not only templates, despite the name.

Guidelines

Limit scope

Styles must apply only to the associated template's output by using specific CSS selectors.
Styles may also apply to highly-relevant nearby wikitext where the template is used. (For example, there are many table templates which should have TemplateStyles which are provided entirely in templates, or which may provide a legend to a wikitext table.) It would otherwise be confusing if adding a template to one part of a page were to completely or partially change the display or styling of an unrelated part of the page.

Naming convention

Style pages must be clearly associated with their templates or modules and named accordingly (e.g. Template:Blockquote uses Template:Blockquote/styles.css).
The naming convention is to save the stylesheet for an associated page, template or module in a subpage of said page called /styles.css. This ensures the page automatically has the correct content model (sanitized-css) and can be easily identified as a style page.
Style pages should be associated with a specific template/module or group of templates/modules, and named accordingly. This allows style pages to be easily identified and edited. In general, this means that a style page should be a subpage of the related template, e.g. Template:myTemplate/styles.css or Template:myTemplate/styles-foo.css, but not Template:styles-foo.css nor Template:foo.css.
A sandbox for a template or module's style page should be associated with its sandbox page by appending /styles.css to the /sandbox page. e.g. Template:myTemplate/sandbox/styles.css, but not Template:myTemplate/styles.css/sandbox.

Coding conventions

In general, follow MediaWiki CSS coding conventions. Some specifics:

Use specific selectors unique to the template. This reduces the chance of conflicting CSS rules arising accidentally. For example, .myTemplate-row rather than .row, and .myTemplate tr rather than tr.
Avoid #id selectors where ID is the HTML ID attribute. HTML IDs are supposed to be unique on a page. Templates are rarely used uniquely, and those that are initially single-use-per-page are often later used in unanticipated ways. Use classes instead of IDs for styling.
Avoid !important unless absolutely required, except in mobile view to override style input from the associated template. Use of !important is exceptionally difficult to override because of the loading order of styles (personal CSS then TemplateStyles).
In templates that will be substituted, instead of transcluded, nest the stylesheet inside the second parameter of {{ifsubst}} to ensure it is not included when substituted.
- For example, {{ifsubst| | <templatestyles src="..." /> }}, and {{allcaps}}. Inline styles may be used in the first parameter in a substituted template. Example: {{smallcaps}}.
Only use public domain images as CSS backgrounds.
The Protection level of the stylesheet must match that of the template. Add /* {{pp-template}} */ to the top of protected CSS pages.
Manual of Style and accessibility guidelines, such as the guidelines related to color contrast, still apply.

Workflow for conversion

A simplified step-wise workflow to convert inline styles in templates to use a CSS stylesheet with TemplateStyles.

In Template:myTemplate, identify all of the inline styles that can be moved to a separate stylesheet.
Create Template:myTemplate/styles.css containing all the classes that will replace the inline styles. Use template-specific class names where possible.
In Template:myTemplate (or its Template:myTemplate/sandbox if you want to test first), add <templatestyles src="myTemplate/styles.css"/> (you do not have to specify the Template: namespace). It is preferable to include it as the first wikitext, as only the wikitext after it is called will have the styles applied to it. It also ensures that it is prominent and avoids a flash of unstyled content.
It needs to be on its own line if the template starts with wiki markup that must start at the beginning of a line, as is the case with wikitables:
```
<templatestyles src="myTemplate/styles.css"/>
{| class="wikitable"
|-
...
|}
```
Amend the template (or sandbox) to replace the inline styles with the classes you defined in Template:myTemplate/styles.css
Tracked in Phabricator
Task T200704
Open
Do as much checking as you can. Check that the results on the testcases subpage render properly, and add new test cases as needed to ensure broad coverage of how the template is used. (If necessary, create the testcases subpage to perform testing.)
- For templates used inline (versus block 'box' content), specifically ensure the template is not transcluded inside a wikilink. TemplateStyles of templates will not work inside links (as of 2025^[update]).
If you used the sandbox, either make an edit request or copy the changes across to the main template yourself if you are confident in your changes.
Request to have amended or amend the protection level of Template:myTemplate/styles.css to match that of Template:myTemplate as necessary.
Add {{Uses TemplateStyles|Template:myTemplate/styles.css}} to the template's documentation.

Tips

Uses of TemplateStyles stylesheets are recorded just like template transclusion and Scribunto module invocation. Special:WhatLinksHere and the "Templates used in this preview" section beneath the edit form will work for them in the usual manner.
To search for TemplateStyles stylesheets, you can search for contentmodel:sanitized-css. See also mw:Help:CirrusSearch#Contentmodel.
When {{Uses TemplateStyles}} is placed on a template's documentation, it adds the template to Category:Templates using TemplateStyles. If the TemplateStyles stylesheet has a lower protection level, the template will be tracked in Category:Templates using TemplateStyles with a different protection level (1 page).
TemplateStyles experiments can be created at Template:TemplateStyles sandbox, e.g. for use in Module:Sandbox module experiments.
A TemplateStyles page can be created outside of the template or module namespaces with these methods:
- First create it in template namespace (perhaps at Template:TemplateStyles sandbox) and move it.
- Autoconfirmed users can use Special:ChangeContentModel to create a new page with sanitized CSS in most namespaces.
- Administrators and template editors can use Special:ChangeContentModel to change an existing page to sanitized CSS. They can start on "Page information" for the page and click "change" at "Page content model".
Regardless of what method is used, creating a .css page in userspace can only be done by the user in question or an interface administrator, but once it is created anyone can edit it if it is sanitized CSS. A .css page in the MediaWiki namespace can only be created and edited by interface administrators and global interface editors.
Moving a sanitized CSS page will not create a redirect. The page remains sanitized CSS at the new name.

Overriding TemplateStyles

Because of the way TemplateStyles is implemented, overriding TemplateStyles in your personal CSS requires a little more effort than normal. The rules on a specific TemplateStyles sheet are not the full CSS rules, nor can you match the selectors to override them.

Each selector is 'hoisted' to .mw-parser-output, so to override a rule in a TemplateStyles sheet that looks like .documentation {}, a naive override in your personal CSS file would need to look like .mw-parser-output .documentation {}.
However, in the HTML each TemplateStyles style is always placed after your personal CSS file loads. Accordingly, the new rule would need to be more specific. That can come in a couple ways. The easiest is to select the HTML element also as in: .mw-parser-output div.documentation {}. Another way would be to double one of the class selectors, as in .mw-parser-output.mw-parser-output .documentation {} or .mw-parser-output .documentation.documentation {}. This latter way is a little more future-proof but looks a little weirder.
Lastly, !important can always override styles in your personal CSS. The usual caveats regarding !important apply. Prefer one of the two options in bullet two if possible. (You must do this to override inline styles, regardless of any of the above; some templates cannot move everything to TemplateStyles per the flexibility given to template users. Implementers of templates should consider whether parameters like style and width are actually necessary. See also phab:T200632.)

Examples

mw:Help:TemplateStyles/examples
- mw:Template:Stylish (CSS)
- mw:Template:ResponsiveAmboxExample (CSS)
Template:Thermometer and Template:Thermometer/styles.css give a simple demonstration of how TemplateStyles may be mixed with inline styles (where a parameter is passed to change one or more styles)

Notes

↑ For example, for <table id="wikibase-full-name" class="wikibase-item" /> avoid using table#wikibase-full-name but rather table.wikibase-item.
↑ When a template is substituted, its wikitext is copied directly into the page rather than being transcluded. If the </templatestyles> tag remains after substitution, this may confuse non-technical users.
↑ Images that do not require attribution
↑ Any templates using CSS pages with the wrong protection level are categorized in Category:Templates using TemplateStyles with a different protection level. Protected templates using CSS pages that lack the lock icon are categorized in Category:Templates using TemplateStyles without padlocks.

External links

[1] For example, for <table id="wikibase-full-name" class="wikibase-item" /> avoid using table#wikibase-full-name but rather table.wikibase-item.

[2] When a template is substituted, its wikitext is copied directly into the page rather than being transcluded. If the </templatestyles> tag remains after substitution, this may confuse non-technical users.

[3] Images that do not require attribution

[4] Any templates using CSS pages with the wrong protection level are categorized in Category:Templates using TemplateStyles with a different protection level. Protected templates using CSS pages that lack the lock icon are categorized in Category:Templates using TemplateStyles without padlocks.