$fonts — Thesis Skin API Object

The $fonts object is a simple tool that handles fonts within Thesis. With it, you can:

  • Register new fonts for use with the thesis_fonts array filter
  • Access font-family declarations for use in CSS with the family() method

Any fonts registered with the $fonts object will appear in font <select> elements in the Design Options.

In addition, the registered fonts contain a CSS font-family declaration that Skin developers can reference in the css_variables() method.

By default, the $fonts object includes common web-safe fonts along with standard fonts for Windows and Mac operating systems. Here’s the entire list of default fonts included in the Thesis $fonts object.

What about Google Fonts? Optional Google Fonts functionality adds all Google Fonts that come with 400, 400 italic, and 700 weights.

Registering New Fonts for Use

If you’re a Skin developer and would like to register new fonts for use with your Skin, then you should use the handy fonts() method from the Skin API.

If you’re not a Skin developer but would still like to register fonts for use on your site, you’ll need to take a slightly different approach by using the thesis_fonts array filter.

Here’s an example for adding Proxima Nova from Typekit:

add_filter('thesis_fonts', 'add_my_font');

function add_my_font($fonts) {
	$fonts['Proxima Nova'] = array(
		'family' => '"Proxima Nova", sans-serif');
	return $fonts;
}

Notice how the add_my_font function includes a $fonts parameter and simply adds Proxima Nova to it. This ensures you do not overwrite any other fonts that have been registered with Thesis.

In the next section, we’ll take a closer look at the array format used to register fonts with Thesis.

Thesis Font Array Format

Any fonts registered with the $fonts object must adhere to the Thesis font array format in order to work properly. Here’s a sample array structure:

$fonts[$name] => array(
	'family' => $family,
	'x' => $x,
	'mu' => $mu);
  • $name — (required) font name as it will appear in the Thesis interface
  • $family — (required) CSS font-family declaration for this font
  • $x — (optional) x-height ratio for this font
  • $mu — (optional) character constant for this font

The first two parameters are self-explanatory, but the third and fourth require some explanation.

The third parameter, x, refers to the x-height of the current font. The Thesis $typography object uses this x-height value to achieve absolute precision when calculating line heights and layout spacing.

The fourth parameter, mu, is useful for determining the resulting characters per line (CPL) when the current font is used within a specific width.

When adding your own fonts to Thesis, you’ll likely want to omit the x and mu parameters. Without these two values, Thesis will simply use the golden ratio to determine typography and layout spacing.

Using the $fonts Object to Output font-family in CSS

Attention! This section contains example code that is only pertinent to Skin developers.

When a font is registered with Thesis and then selected in the Design Options, Thesis only saves the associative array key for that font.

For example, if a user were to select the Proxima Nova font we registered in the sample code above, the Proxima Nova array key is what would actually get saved.

If you’re a Skin developer who is attempting to modify CSS based on a user’s font selection, that data is not particularly useful to you. What you really need is the font stack for that font so you can output the appropriate font-family declaration in your CSS.

Fortunately, the $fonts object contains a handy method, family(), that enables you to grab a font-family when all you know is the font array key.

In the following example, we’ll assign a font-family to a CSS Variable inside the css_variables() method:

public function css_variables() {
	$vars['font'] = $this->fonts->family(!empty($this->design['font']) ? $this->design['font'] : 'georgia');
}

In the above code, if the user has selected a font for the font option, then Thesis will store the font-family for the selected font in $vars['font'].

If the user has not selected a font, then $vars['font'] will receive the Georgia font-family by default.

Default Fonts in Thesis

The following web-safe fonts are included in the $fonts object:

  • Arial
  • Arial Black
  • Arial Narrow
  • Courier New (monospace)
  • Georgia
  • System UI
  • Times New Roman
  • Trebuchet MS
  • Verdana

The fonts below are also included but are not considered web-safe. They are standard on Windows and/or Mac operating systems:

  • American Typewriter
  • Andale Mono (monospace)
  • Baskerville
  • Calibri
  • Cambria
  • Candara
  • Consolas (monospace)
  • Constantia
  • Corbel
  • Gill Sans
  • Helvetica Neue
  • Hoefler Text
  • Lucida Grande
  • Menlo (monospace)
  • Monaco (monospace)
  • Palatino
  • Tahoma