Wikipedia:TemplateStyles

CSS logo

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.
• For example, if a template {{MyTable}} outputs a styled table, its stylesheet might contain selectors and rules that only affect elements inside the template output, such as those below on the left.
• However, if the stylesheet used a generic selector, like those below on the right, it would unintentionally re-style all tables on the page, even those unrelated to {{MyTable}}.

Yes

.MyTable-table {
    border: 1px solid var(--border-color-base, #bbb); 
}

.MyTable-header {
    background: var(--background-color-base, #fff);
    color:inherit;
    font-weight: bold; 
}

No

table {
    border-collapse: collapse;
}

th {
    background: yellow;
    color:inherit;
}

Naming convention

• Style pages must be clearly associated with their templates 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.
• Style pages should be associated with a specific template or group of templates, 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.
• Prefer the block element modifier (BEM) naming convention, with tpl-* as a prefix to indicate 'template' tpl-blockname__elementname--modifiername:
  • Block: A standalone entity such as .tpl-infobox, .tpl-header or .tpl-card
  • Element: A part of a Block that has no standalone meaning and is semantically tied to its parent Block. Such as .tpl-menu__item, .tpl-card__title, or .tpl-infobox__logo.
  • Modifier : A flag on a Block or Element used to change its appearance. Such as .tpl-card--large, or .tpl-title--bold

Coding conventions

Main article: mw:Manual:Coding conventions/CSS

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| |  }}, 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.

1. In Template:myTemplate, identify all of the inline styles that can be moved to a separate stylesheet.
2. Create Template:myTemplate/styles.css containing all the classes that will replace the inline styles. Use template-specific class names where possible and the BEM naming convention, for example .tpl-name-title__text, or .tpl-name-body__image.
3. 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 on a newline, as is the case with wikitables:

<templatestyles src="myTemplate/styles.css"/>
{| class="wikitable"
|-
...
|}

4. Amend the template (or sandbox) to replace the inline styles with the classes you defined in Template:myTemplate/styles.css
5. Tracked in Phabricator
   Task T200704
   Open
   Do as much checking as you can. If you tested in the sandbox you can check the testcases page where it exists, but specifically check that the styles you affected render properly.
   • 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).
6. 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.
7. Request to have amended or amend the protection level of Template:myTemplate/styles.css to match that of Template:myTemplate as necessary.
8. 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 (0 pages).
• TemplateStyles experiments can be created at Template:TemplateStyles sandbox, e.g. for use in Module:Sandbox module experiments.
• TemplateStyles pages can be created outside of the template or module namespaces by either first creating them in template namespace and moving them (perhaps at Template:TemplateStyles sandbox), or by using Special:ChangeContentModel as an admin or template editor. Regardless of what method is used, creating a .css page in userspace can only be done by the user in question or an interface admin, but once it is created anyone can edit it.
• Moving a sanitized CSS page will not create a redirect.

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.

1. 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 {}.
2. 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.
3. 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)

See also

• Wikipedia:Lua
• MediaWiki talk:Common.css/to do, where conversion from Common.css, Mobile.css, and skin.css to TemplateStyles is being tracked

External links

• mw:Extension:TemplateStyles
• mw:Help:TemplateStyles