Doing this guarantees that the style sheet finishes loading before any attempts to replace text are made.

CSS properties

Cufón supports most text-related CSS properties out-of-the-box, making Cufón-specific CSS rules completely unnecessary in most cases. However, extra care is sometimes needed with the following properties:

color

Cufón extends the CSS color property to support gradients. Here’s an example. They work like this:

Cufon.replace('h1', {
color: '-linear-gradient(white, black)'
});

The colors go from top to bottom, which means that in this case the top would be white, eventually fading to black at the bottom. You may use any CSS2 color value, and naturally you may specify more than two colors:

The stops go from 0 to 1. If you choose to specify the values manually it is your responsibility to make sure that stops 0 and 1 have a value.

Only linear gradients going from top to bottom are supported at this time.

font-size

Due to differences in the way browsers return computed CSS values, the size of the replaced text may vary by one pixel. This is usually very hard to even notice, but in case you need absolute control you may specify a pixel value instead, either in the CSS file itself or as a configuration setting during replacement.

font-style

For reasons unknown to mankind, Internet Explorer, by default, reports the font-style of <em> and <i> as “normal”, not “italic”. This can cause quite a bit of confusion. Your best bet is to have the following in your stylesheet:

em, i {
font-style: italic;
}

and the issue is no more.

font-weight

Internet Explorer and Opera, by default, use font-weight: bold for <strong> and <b>. Gecko- and WebKit-based browsers use font-weight: bolder. In reality you probably don’t have to care about this at all, but if you’re using many different variations of a font with different font-weights this may be an issue. If so, you might want to add the following to your stylesheet to get more consistent results:

strong, b {
font-weight: bold;
}

Unfortunately you cannot use bolder, as Internet Explorer will just increase the existing value of bold instead of overriding it.

line-height

If your text spans multiple rows and you want equal line-height in every supported browser, you must use a value other than “normal” (which is the initial value). The same is true even for regular text, but it is easy to think that cufón might be at fault.

Values lower than 1.2 (which is usually the default) behave as if line-height: 1.2 was set.

You must use a strict (or HTML 5) doctype for line-height to work properly! Otherwise, here’s what you can expect to happen:

Browser

HTML 5

Strict doctype

Transitional doctype

Quirks mode

Internet Explorer 6.0

works

works

works

works

Internet Explorer 7.0

works

works

works

works

Internet Explorer 8.0

works

works

no effect

works

Firefox 1.5-2.0

works

works

works

works

Firefox 3.0+

works

works

no effect

no effect

Safari 3.0+

works

works

no effect

no effect

Opera 9.5+

works

works

no effect

no effect

Chrome 1.0+

works

works

no effect

no effect

opacity (also applies to all kinds of fades)

Internet Explorer requires the element to be positioned. Position: relative will work just fine and should have no effect on your layout. If position is “static” (the default), opacity will have no effect on replaced text. For Internet Explorer 8, the element also needs a z-index value other than “auto” (which is the default). So, this is the minimum code required to make opacity work properly:

selector {
position: relative;
z-index: 1;
}

overflow

If the element that contains the replaced text (or any of its ancestors) has overflow set to any other value than “visible”, the replaced text may stay in place when the element in question is scrolled, just as if it had position: fixed set. This is an old, known bug in Internet Explorer, often used to achieve a position: fixed -like effect. You can get rid of this issue by setting the element with the overflow to position: relative.

text-shadow

Partially supported. Due to lack of native support in many browsers, this value cannot be read from CSS, and must be specified as an option instead. Offsets defined in units other than pixels are not supported, neither is blur. Here are a few examples.

visibility

Internet Explorer 8 has some serious issues displaying Cufónized content within elements that have visibility: hidden set. Please see FAQ 9, or use display: none instead (which works perfectly).

word-spacing (since: 1.04)

Word-spacing was not supported until version 1.04.

:hover

For performance reasons :hover is not enabled by default, which means that you’ll have to enable it separately for elements that need it. You can do this with:

Cufon.replace('h1', {
hover: true
});

By default cufón will only apply :hover effects to links (<a>). You can change this with:

Note that you cannot add a hover effect to an element that has already been replaced. You can, however, replace the hoverable element first and then the parent element after that. The hover effect will still apply.

Special cases

Sometimes you may wish to apply special styling to Cufón-enabled elements. Here’s how:

cufon-active

This class name is added to the root element (usually <html>) when Cufón is both supported and used. A possible use case may be to set a larger font-size:

.cufon-active h1 { /* for Cufon.replace('h1') */
font-size: 3em;
}

cufon-loading

Similar to cufon-active, but only available when the document and/or CSS style sheets are still loading. This makes it possible to hide elements while they’re still waiting for their turn to be processed:

As soon as everything’s up and running cufon-loading is removed from the root element and things become visible again.

cufon-ready (since: 1.02)

Works opposite to cufon-loading. Added to the root element right after cufon-loading has been removed, just when Cufon.replace() calls are about to be executed for the first time. Meant for last minute CSS changes.