Simo Kinnunen edited this page Sep 7, 2011 · 29 revisions

The Cufón API is simple yet powerful. We aim to keep it 100% backwards-compatible to make updating as painless as possible; just replace your old cufon-yui.js with a new one and you’re good to go.

All API methods return the Cufon object, which means that it’s possible to chain them. For example, the following is completely legal:

Cufon.set('fontFamily', 'Amaze').replace('h1')('h2');

Tells Cufón that the DOM is ready and it’s OK to start replacing stuff. Needed for Internet Explorer, otherwise there will likely be a short delay before Cufón does its thing. Applies to other browsers as well in case you’ve got any external scripts in the <body> of the document.

Should be placed at the bottom of the HTML document, usually right before the closing </body> tag. If you’ve got external scripts (such as Google Analytics) already there, should go before them.

Using with Google Analytics

		<script type="text/javascript">; </script>

		<script type="text/javascript">
		var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
		document.write(unescape("%3Cscript src='" + gaJsHost + "' type='text/javascript'%3E%3C/script%3E"));

		<script type="text/javascript">
		try {
		var pageTracker = _gat._getTracker("your-analytics-code");
		} catch(err) {}</script>


See Special cases at Styling for alternative solutions.

Cufon.refresh([selector, ..])

If given one or more selectors, repeats Cufon.replace() calls with the matching selectors. Otherwise repeats all Cufon.replace() calls. Useful if you’ve got Ajax content that needs Cufón, or if text size has changed.

Remembers options that were used with the original Cufon.replace() call.

Replacing Ajax content with MooTools

$('id').set('load', { onSuccess: Cufon.refresh }).load('/feed');

Replacing Ajax content with jQuery

$('selector').load('/feed', Cufon.refresh);

Replacing ALL Ajax content with jQuery, including any future Ajax requests

$(document).ajaxSuccess(function() {

Refreshing a limited selection

Cufon.replace('h1', {
	textShadow: '1px 1px rgba(0, 0, 0, 0.2)'

// ..

$('#page').load('content.html', function() {

Cufon.replace(selector[, options])

Well, does the obvious. Also, calling Cufon() is equivalent to using Cufon.replace(), i.e. Cufon('h1') is the same as Cufon.replace('h1').

selector can be either a CSS selector (assuming you’ve loaded a compatible selector engine), an element or a collection of elements.

Using Cufon.replace() with CSS selectors

Cufon.replace('#content > h3');

Using Cufon.replace() with DOM methods (assumes that the DOM is ready)


Using Cufon.replace() with DOM methods (when it is unknown whether the DOM is ready)

Cufon.DOM.ready(function() {


options is a JavaScript object containing special instructions for Cufón. The options are listed below.

Option Description Possible values Default value
autoDetect If true, font-family is read from CSS instead of the fontFamily option. Does not work in Opera, which is why the option is disabled by default. (since: 1.04) true, false false
color The color of the text. Defined in CSS, unless you’re using gradients (see Styling for more information). ‘red’, ‘#f62315’, .. Defined in CSS
fontFamily The name of the font you’d like to use. Defaults to the name of the font that was loaded last (i.e. last <script>). Name of any loaded font The name of the last font
fontSize The size of the font. Defined in CSS, you should not touch this value. Only use pixel values if you do. ‘14px’, ‘24px’, ‘72px’, .. Defined in CSS
fontStretch CSS3, cannot be defined in CSS. Goes against the specs by stretching the original font instead of choosing a suitable stretched variant. See all possible values and what they map to. ‘160%’, ‘condensed’, ‘semi-expanded’, .. ‘normal’
fontStyle The style of the font. Defined in CSS, the best match is chosen by default. ‘normal’, ‘italic’, ‘oblique’ Defined in CSS
fontWeight The weight of the font. Defined in CSS. The best match is chosen by default. You might have to adjust this value for rarer weights if you’re using multiple variants of a font. 100-900, ‘normal’, ‘bold’ Defined in CSS
forceHitArea Fixes hit area for mouse events in Internet Explorer. Enabling hover also enabled this option. true, false false
hover Whether or not :hover is enabled. For performance reasons this option disabled by default. If an Object, :hover will be enabled and the values of the object will override normal options on :hover. See below for an example. Note: the hover option cannot be added to an element that has been replaced before. To make it work you must reverse the order of your replace calls (i.e. hover calls must go first). true, false, Object false
hoverables Defines which elements :hover is used with. Defaults to links only as IE6 can’t handle anything else. { tag: true, .. } { a: true }
ignoreClass Allows you to ignore elements based on a single or multiple class names. If an element matches one of the class names, it will not be processed by Cufón. Its children will be left alone too. (since: 1.10) ‘nocufon’, ‘nocufon skipcufon’ null
letterSpacing The space between letters, in addition to kerning (if enabled). Defined in CSS. ‘-1px’, .. Defined in CSS
modifyText A callback function that runs before a piece of text is replaced for the first time. Must return a new string, which will then be rendered in place of the old value. Receives four arguments: textString, textNode, element and options. (since: 1.10) function null
onAfterReplace A callback function that runs after an element has been replaced. Receives two arguments: element and options. Child elements trigger this callback too. (since: 1.10) function null
onBeforeReplace A callback function that runs before an element gets replaced. Receives two arguments: element and options. Child elements trigger this callback too. (since: 1.10) function null
selector The selector engine to use. Defaults to the selector engine of whatever framework you’re using, or document.getElementsByTagName otherwise. JavaScript function Provided by the JS framework
separate How to separate pieces of text. By default each word is considered a unit of its own, which works well with multi-line text. ‘none’ is only suitable for single lines of text. ‘words’, ‘none’ or ‘characters’ ‘words’
softHyphens Whether soft hyphens are enabled or not. Note that soft hyphens inside invisible (display: none) content are not supported because their coordinates cannot be calculated. (since: 1.10) true, false true
textShadow Renders text shadows. See Styling for examples. Can be defined in CSS but many browsers do not support it. ‘1px 1px #000’, .. ‘none’
textTransform How to transform the text. Defined in CSS. ‘uppercase’, ‘lowercase’, ‘capitalize’, ‘none’ Defined in CSS
trim If ‘simple’, trims all preceding and following whitespace in adjacent text nodes. If ‘advanced’, attempts to be more intelligent (i.e. does not simply remove everything). Note that ‘simple’ can be too simple, and ‘advanced’ not intelligent enough. Whitespace problems can usually be fixed by using a less greedy selector (e.g. Cufon.replace('body') is very bad, Cufon.replace('h1') much better). (since: 1.10) ‘simple’, ‘advanced’ ‘advanced’

Using options with Cufon.replace()

Cufon.replace('h1', {
	color: '-linear-gradient(white, black)',
	fontFamily: 'Scriptina',
	textShadow: '1px 1px rgba(0, 0, 0, 0.2)'
Cufon.replace('#nav a', {
	hover: true
Cufon('#content h2', {
	color: '-linear-gradient(#b7dded, 0.2=#70ceef, 0.5=#20b4e2, #b1dbeb)',
	hover: {
		textShadow: '2px 2px red',
		color: '-linear-gradient(black, white)'

Cufon.set(option, value)

Sets the default value for an option. For example, you might want to do the following:

Cufon.set('fontFamily', 'Nifty Font');

Cufon.replace('#sidebar h2');
Cufon.replace('#content .title');

Cufon.set('fontFamily', 'Another Nice Font');

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.