drewgreenwell

Theming Metro JS

Need a custom tile size? Try the Theme Generator

Want to customize tile sizes for your layout? Check out the theme generator to tweak Metro JS to your site theme.

Metro JS
Metro JS

Base Theme and Accent Color

Metro JS Themes are based on the default Windows Phone themes. There are two base themes and twenty accent colors. Base themes apply to the entire page; accents only apply to a specific element and its children.

The 'base' theme has two options, 'dark' and 'light'. The dark theme will color the body of the page black and use white font. The 'light' theme uses a white body color and black font.

The 'accent' color has twenty options. The available accent color classes are amber, blue, brown, cobalt, crimson, cyan, emerald, green, indigo, lime, magenta, mango, mauve, olive, orange, pink, purple, red, sienna, steel, teal, violet, yellow.

Base Themes

Accent Colors

Theming Live Tiles

Live tiles in Metro JS get their accent color one of two ways.

  1. An accent color class applied directly to the live-tile.
  2. An accent color class applied to a parent of the live-tile.

If you are using the application bar then you get the themes support for free. (Note: by default the light/dark theme is set on the body and the accent color is applied to a div with the "tiles" class).

In Metro JS the theme colors can be applied to any live-tile/list-tile or to any parent of the tile. By default, when you call $.fn.metrojs.theme.applyTheme with an accent color or use the applicationBar Metro JS looks for a div with the 'tiles' class to add a color class to. When you choose a color on the applicationBar, the applyTheme method is called for you on the default element ( 'tiles' ). You can override which class is used by passing it in the applicationBar options or by overriding the theme defaults object ( $.fn.metrojs.theme.defaults )

Example tiles container with color

<div class="tiles mango">
<!-- some live tiles -->
</div>
Example Live Tile with color applied directly

<div class="live-tile red">
<div>A tile! </div>
</div>

You can change between dark and light base themes with the 'dark' and 'light' classes. The default location for this class is on the body element. Again this can be overridden on the defaults option above, passed as an option to the applicationBar, or set using $.fn.metrojs.theme.applyTheme

The Accent Classes

Metro JS also has support for highlighting your content in several ways using a set of 'accent' prefixed classes. The available classes and their effects are detailed below.

Important: These classes affect the current element and any children of that element.

Custom Tile Sizes and Layouts

Starting with version 0.9, Metro JS includes support for custom layouts based off of your default tile size. The default tile size for Metro JS 0.9 is 150x150 pixels with a 5px margin, you can change the default tile size for Metro JS using the Theme Generator ( more info ). As always you can define your own Live Tile height, width and margin with CSS or JavaScript, but the Theme Generator will lesson the burden of calculating all of the possible sizes for tile layouts that Metro JS now offers.

All tiles and tile layout classes support #-tall and #-wide modifiers to set the height and width of the tile or container. #-tall and #-wide modifiers support the prefixes half, one, two, three, four, five, six, seven, eight, nine and ten. Metro JS also includes single tile classes for half-tile (short hand for "half-tall half-wide") and one-tile (useful for wrapping small tiles).

An Example Custom Layout

three-wide

half-tall

half-tall

default
half-tile
half-tile
half-tile
half-tile

two-wide

The Code

Notes:

  • The .tile-group CSS class is intended to be a wrapper for an entire set of tiles. As an example, each tile section on my home page ( Welcome, Metro JS, Things and Stuff ) has a tile-group class applied to it class="tile-group"
  • The .tile-strip CSS class is intended to wrap a group of tiles within a tile-group.

<div class="tiles tile-group four-wide">    
    <div class="tile-strip four-wide">
        <div class="live-tile three-wide"><div></div></div>
        <div class="live-tile half-tall"><div></div></div>
        <div class="live-tile half-tall"><div></div></div>
    </div>
    <div class="live-tile"><div></div></div>
    <div class="tile-strip one-tile">
        <div class="live-tile half-tile"><div></div></div>
        <div class="live-tile half-tile"><div></div></div>
        <div class="live-tile half-tile"><div></div></div>
        <div class="live-tile half-tile"><div></div></div>
    </div>
    <div class="live-tile two-wide"><div></div></div>
</div>

Using the Theme Generator

Metro JS offers a fully featured theme generator to make it easy to compile Metro JS based on your size requirements and with only the colors you need. The 'default tile size' is used to calculate the size of the #-wide and #-tall classes ( two-wide, half-tall, etc. ). Basic steps to use the theme generator are listed below.
  1. Enter the height, width, and margin you would like to use for a single tile in the Size Options section
  2. In the CSS to Compile section, you can choose which Metro JS modules you want to include.
  3. If you have included theme support, choose the Accent Colors that you would like to include
  4. You can add any custom accent colors by adding in the name of the accent color and the color value e.g. red, #ff0000, rgb(255, 0, 0),...
  5. If you don't need to make any further modifications, you can choose to minify the CSS results in the Compile Options section
  6. Click Generate Theme to compile your CSS and generate a preview of your theme.
  7. That's it! Save the theme in a file, include it on your page, and start making cool stuff!

$.fn.metrojs.theme

The metrojs.theme object contains default theme properties and methods for applying themes or loading a user's previous theme. The options and methods are detailed below.

metrojs.theme.defaults

  • Name baseThemeCssSelector   Type string selector
    Description
    selector to place dark or light class after load or selection
    Default Value 'body'
  • Name accentCssSelector   Type string selector
    Description
    selector to place accent color class after load or selection
    Default Value '.tiles'
  • Name accentColor   Type string
    Description
    the default accent color. options are amber, blue, brown, cobalt, crimson, cyan, emerald, green, indigo, lime, magenta, mango, mauve, olive, orange, pink, purple, red, sienna, steel, teal, violet, yellow
    Default Value 'blue'
  • Name baseTheme   Type string
    Description
    the default theme color. options are dark, light
    Default Value 'dark'
  • Name accentColors   Type array
    Description
    the default accent colors
    Default Value [amber, blue, brown, cobalt, crimson, cyan, emerald, green, indigo, lime, magenta, mango, mauve, olive, orange, pink, purple, red, sienna, steel, teal, violet, yellow ]
  • Name baseThemes   Type array
    Description
    the default base themes
    Default Value [dark,light ]
  • Name accentListTemplate   Type string
    Description
    template to use for list items
    Default Value
    <li><a href='javascript:;' title='{0}' class='accent {0}'></a></li>
  • Name accentListContainer   Type string selector
    Description
    the default theme option container selector
    Default Value .theme-options
  • Name baseThemeListTemplate   Type string
    Description
    template to use for list items
    Default Value
    <li><a href='javascript:;' title='{0}' class='accent {0}'></a></li>
  • Name baseThemeListContainer   Type string selector
    Description
    the default base theme option container selector
    Default Value .base-theme-options

metrojs.theme Methods

  • Name theme.loadDefaultTheme Data Attribute theme.loadDefaultTheme() Type function
    Description

    Checks for a previously selected theme and applies it or uses the default options.

    stgs: optional. object containing values to use if no defaults have been set by the user. When null or undefined this points to the metrojs.theme.defaults object.
    Default Value
    Example 
    
var metrojs = $.fn.metrojs;
metrojs.theme.loadDefaultTheme();
  • Name theme.applyTheme Data Attribute theme.applyTheme(baseTheme, accent) Type function
    Description

    Applies a base theme or color by name.

    baseThemeColor: optional. string name of the base theme. More info
    accentColor: optional. string name of the accent color. More info
    stgs: optional. object containing values to use if no defaults have been set by the user. When null or undefined this points to the metrojs.theme.defaults object.
    Default Value 'dark', 'blue' Options optional - string, string
    Example 
    
var metrojs = $.fn.metrojs;
metrojs.theme.applyTheme('dark', 'blue');
// or
// metrojs.theme.applyTheme(null, 'red');
// or
// metrojs.theme.applyTheme('light');
  • Name theme.appendBaseThemes Data Attribute theme.appendBaseThemes( { options } ) Type function
    Description

    Appends the current list of base themes to the default container unless an alternate container is specified.

    stgs: optional. object containing values to use if no defaults have been set by the user. When null or undefined this points to the metrojs.theme.defaults object.

    Options from theme.defaults used

    baseThemes: optional. an array of base theme classes to append
    baseThemeListTemplate: optional. HTML template to use for the baseThemes list with {0} used to determine where the base theme will be placed.
    e.g. "<li><a href='javascript:;' title='{0}' class='accent {0}'></a></li>"
    baseThemeListContainer: optional. string selector to decide where baseThemeListTemplate is appended.
    Default Value Options optional - { }
    Example 
    
var metrojs = $.fn.metrojs;
metrojs.theme.appendBaseThemes();
// or if you want your own template
// metrojs.theme.appendBaseThemes({ baseThemeListContainer: '#MyBaseThemes'  });
  • Name theme.appendAccentColors Data Attribute theme.appendAccentColors( { options } ) Type function
    Description

    Appends the current list of accent colors to the default container unless an alternate container is specified.

    stgs: optional. object containing values to use if no defaults have been set by the user. When null or undefined this points to the metrojs.theme.defaults object.

    Options from theme.defaults used

    accentColors: optional. an array of accent color classes to append
    accentListTemplate: optional. HTML template to use for the accentColors list with {0} used to determine where the accent color will be placed.
    e.g. "<li><a href='javascript:;' title='{0}' class='accent {0}'></a></li>"
    accentListContainer: optional. string selector to decide where accentListTemplate is appended.
    Default Value Options optional - { }
    Example 
    
var metrojs = $.fn.metrojs;
metrojs.theme.appendAccentColors();
// or if you want specific accent colors
// metrojs.theme.appendAccentColors({ accentColors: ['blue','cobalt','mango','red','yellow' ]  });