Skip to content
This repository
  1. Cufón only works in IE 8, Firefox 3.5 and Safari 3.2+. Why?
  2. I can’t get my custom font to show up!
  3. Some characters do not show up at all!
  4. If I disable CSS every word is shown twice!
  5. There’s a delay before anything gets replaced. Can I get rid of it?
  6. My font file is quite large. Can I run the generator offline?
  7. I get this error in IE: “Attribute only valid on v:image”, or sometimes simply “Failed”
  8. Cufón doesn’t work in Internet Explorer 9 Beta!
  9. My Cufónized text is completely hidden in Internet Explorer 8
  10. I have dropdowns/submenus. Sometimes the hover color seems to “stick” when I leave a submenu.
  11. Cufón doesn’t work in Firefox, but works in other browsers

#1) Cufón only works in IE 8, Firefox 3.5 and Safari 3.2+. Why?

For IE9 Beta, see FAQ 8.

Cause

Instead of shipping with a selector engine of its own, Cufón takes advantage of selector engines provided by other JavaScript frameworks, and – if none is loaded – the browser itself. Newer browsers come with built-in selector engines (document.querySelectorAll()) which accept full CSS selectors. Older browsers, however, only have document.getElementsByTagName() which only accepts tag names. This is why simple selectors such as “h1” work in all browsers but more advanced selectors such as “.cufon” or “#nav a” do not.

Solution

Load a JavaScript framework or a stand-alone selector engine before Cufón. Cufón detects most frameworks automatically. Just load your framework of choice before Cufón and you’re done. With jQuery, it’d look something like this (using Google’s content delivery network):

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
<script src="cufon-yui.js" type="text/javascript"></script>

For a more light-weight solution you can use a stand-alone selector engine. We recommend Sizzle.

#2) I can’t get my custom font to show up!

Cause

Either your paths (<script src="..">) are wrong or you’re trying to use a domain-restricted font on a domain it was not meant to be used with.

Solution

Double-check your paths and make sure you’ve whitelisted the correct domains. If in doubt, try generating the font with no restrictions at all (just remember to add them back later). If everything works after that you probably forgot to whitelist the correct domain (or you simply mistyped it).

#3) Some characters do not show up at all!

Cause

This issue can be caused by two things. Either you are not using UTF-8 or your font does not support the characters you need (or you simply forgot to include them when you generated the font). Or your CMS may replace things such as quotes and lines with more fancy looking ones without you even knowing about it.

Solution

Make sure your pages are UTF-8 encoded and that you’ve selected the appropriate glyph ranges. Basic Latin should be enough for most English-only sites. Combine Basic Latin with Latin-1 Supplement and you cover most European languages. You may also wish to select WordPress punctuation if your CMS (WordPress or not) tends to use typographic quotes instead of normal ones.

#4) If I disable CSS every word is shown twice!

Cause

You’re seeing both the Cufón-replaced text and the regular text meant for printing and screen readers.

Solution

There’s none, but we don’t think it’s a problem. Why? Because the only people who disable CSS yet leave JavaScript on are web developers. And they only do that while they’re testing things. If a real user somehow figures out a way to disable CSS, they most likely disable JavaScript too. Mobile browsers with limited or no CSS support either do not support JavaScript at all or at the very least support neither <canvas> nor VML, which mean that Cufón is not activated at all. (Semi-related note: Cufón works on the iPhone and other equally modern mobile browsers)

#5) There’s a delay before anything gets replaced. Can I get rid of it?

Cause

Delays can be caused by many things. The most common cross-browser delay causing issue is having external <script>s (the src attribute is set) in <body>. Even a single Google Analytics script or an embedded Vimeo video / Twitter feed can be enough to cause the issue. Internet Explorer on the other hand does not require anything special for a delay to appear, they come and go “just because”. It’s also possible that your page simply loads very slowly for some reason.

Solution

Either use Cufon.now() (see API) or temporarily hide everything you’re going to replace (see Styling). Cufon.now() alone might not work in all cases.

#6) My font file is quite large. Can I run the generator offline?

Solution

You can run the generator offline or on your own server. Please note that these instructions are meant for advanced users only, if you have trouble understanding them this may not be for you. The instructions apply to OS X and *nix only, it is extremely difficult to install the generator on a Windows machine (but it may be doable via Cygwin if you have enough time on your hands).

First of all, you’ll need Git, PHP and FontForge. On OS X you’ll probably have to use MacPorts to install PHP.

After you’ve got everything installed, simply fire up your terminal and issue the following commands:

git clone git://github.com/sorccu/cufon.git cufon
cd cufon/generate
php convert.php -u "U+??" /Path/To/Font.TTF 1> MyFont.font.js

On OS X, the last command should be:

php convert.php --fontforge /Applications/FontForge.app/Contents/MacOS/FontForge -u "U+??" /Path/To/Font.TTF 1> MyFont.font.js

Assuming you used the official FontForge binary, of course. MacPorts may use a different name for PHP, such as “php5” or “php5-cli”. You’ll want to use the CLI version if multiple versions are offered.

If everything went fine, you should now have a valid Cufón font in your hands. For help, try:

php convert.php --help

#7) I get this error in IE: “Attribute only valid on v:image” (sometimes simply “Failed”)

Cause

This is most commonly caused by something accessing the “type” attribute of a VML element. While that may not sound problematic, it is. Here’s what happens. When you access certain VML attributes on VML elements that do not support those attributes, IE, for some reason, decides that the best course of action is to invalidate the whole element and prevent any further access to any of its attributes. A debugger is usually of no help, as this error doesn’t occur when the illegal attribute is accessed, but later in your code when you access an attribute again. The reported line number and file will often have nothing to do with the issue.

Solution

We can’t fix this. This problem is almost always caused by a 3rd party script, sometimes your own code. Solving the problem requires lots of JavaScript debugging experience. The Cufón Google Group may be able to help if you are unable to solve this problem by yourself (but please do at least give it a try first). Note that you will need to post a link to your site, as there is no universal fix for this issue and we will need to see your code.

Things to look out for in your own code:

$(':checkbox, :radio')

These jQuery selectors are not limited to input elements and will go through and access the “type” attribute of all elements they can find. The easiest fix is to simply include tag names in the selectors, like so: $('input:checkbox, input:radio'). It’s faster too.

Problematic 3rd party scripts:

  • Omniture Web Analytics (just older versions?)
  • Some PNG fixes

#8) Cufón doesn’t work in Internet Explorer 9 Beta!

Solution

This was fixed in 1.09i. Just download a new cufon-yui.js from the official site and you’re good to go. It’s fully backwards-compatible too.

Here’s what you can do if you don’t want to update your cufon-yui.js for some reason:

<!--[if gte IE 9]>
	<script type="text/javascript">
		Cufon.set('engine', 'canvas');
	</script>
<![endif]-->

Place it in your HTML before all the Cufon.replace() calls and you’re good to go. You don’t necessarily have to use conditional comments but you get the idea; only IE9 (and greater) should see this rule.

Alternatively you can force IE9 to behave like IE8 (or 7):

<meta http-equiv="X-UA-Compatible" content="IE=8" />
<meta http-equiv="X-UA-Compatible" content="IE=7" />

#9) My Cufónized text is completely hidden in Internet Explorer 8

Cause

This is a bug in Internet Explorer 8. If you have visibility: hidden set on an element that contains Cufónized text you will likely encounter this bug. The bug only occurs if the visibility property is set before Cufón has actually done anything yet.

Solution

There are a couple of solutions for this issue. Listed in order of simplicity:

Use display: none instead

Pros: Very simple.
Cons: If your JS relies on reading dimensions from within this element (or from the element itself) it will fail.

Use opacity (and MS filters) instead

Pros: Relatively simple.
Cons: You have to remember to write an alpha filter for IE. It can also sometimes cause other issues such as ugly black outline around your text.

Temporarily remove visibility: hidden when Cufón is doing its thing

Pros: Works great with 3rd party scripts that you don’t want to modify.
Cons: Complicated, requires multiple steps. Code below.

Step 1 – Locate the element that has visibility: hidden set. It’s going to be either the element you are replacing, and/or at least one of its ancestors. Let’s assume that you found something like this:

#menu li ul { visibility: hidden }

Step 2 – Add a new rule as follows

.cufon-replacing #menu li ul { visibility: visible; display: none }

Note that the selector is the same, but has been prepended with .cufon-replacing, which we’ll take care of in a moment. This must be a new rule! Do not overwrite your old rule.

Step 3 – Add this JavaScript code somewhere before all your replace calls. It must always be before the replace calls!

Cufon.CSS.ready(function() {
  Cufon.CSS.addClass(Cufon.DOM.root(), 'cufon-replacing');
});

Step 4 – Add this JavaScript code somewhere after all your replace calls. Just once, after you’ve replaced everything. This must always be after the replace calls!

Cufon.CSS.ready(function() {
  Cufon.CSS.removeClass(Cufon.DOM.root(), 'cufon-replacing');
});

After that it should work, with no other changes required.

#10) I have dropdowns/submenus. Sometimes the hover color seems to “stick” when I leave a submenu.

Cause

By default Cufón only listens to hover events on links. Because the link itself does not contain the submenu, when your mouse leaves the link (even to enter the submenu) this counts as a mouseleave event which pretty much means that Cufón no longer cares about the link until you bring your mouse over it again.

Solution

Here is an example of what your current code may look like:

<ul id="menu">
	<li><a href="#">Home</a></li>
	<li>
		<a href="#">Products</a>
		<ul>
			<li><a href="#">Product 1</a></li>
			<li><a href="#">Product 2</a></li>
			<li><a href="#">Product 3</a></li>
		</ul>
	</li>
</ul>
Cufon.replace('#menu a', { hover: true });

You are going to have to change the replace call depending on what you need. Below are a few scenarios to choose from. When adapting these for your own use case please be especially care not to remove any of the greater-than (>) symbols as they mean a lot, the selectors need to be tied to a specific level. Note that if your menu’s ID is on a wrapper element, you need to add one more > ul after the ID in the selector!

I have two levels (top, sub) and I only want to replace the top level

Cufon.replace('#menu > li', {
	hover: true,
	hoverables: { li: true },
	ignore: { ul: true },
	textless: { li: true }
});

The textless option prevents text directly within the <li> element (which in most cases is just whitespace) from being replaced. The <a> or anything else you have in there will still be replaced. If you do not use this option you might see your menu get a bit taller because of the (erroneously) replaced whitespace.

I have two levels (top, sub) and I want to replace them both

Cufon.replace('#menu > li', {
	hover: true,
	hoverables: { li: true },
	ignore: { ul: true },
	textless: { li: true }
});
Cufon.replace('#menu > li > ul > li > a', {
	hover: true
});

I have three levels (top, sub, sub of sub) and I want to replace them all

Cufon.replace('#menu > li', {
	hover: true,
	hoverables: { li: true },
	ignore: { ul: true },
	textless: { li: true }
});
Cufon.replace('#menu > li > ul > li', {
	hover: true,
	hoverables: { li: true },
	ignore: { ul: true },
	textless: { li: true }
});
Cufon.replace('#menu > li > ul > li > ul > li > a', {
	hover: true
});

#11) Cufón doesn’t work in Firefox, but works in other browsers

Cause

This issue is almost certainly caused by an empty stylesheet (<link rel="stylesheet" href="" />) in your HTML, which causes Cufón’s CSS load detection to fail. This has been happening in recent versions of Firefox only, and seems to occur a lot with purchased WordPress templates. Note that this snippet will cause your browser to load and use your front page as a stylesheet. It’s pretty much the same as href="/". Extra slowness for zero gain.

Solution

Search your HTML for empty stylesheets. Note that the markup on your site may differ from the example, but searching for href="" might save you some trouble. Also, make sure to use the actual HTML (e.g. View Source in your browser) while doing this, if you only go through your template files the issue might be very difficult to spot as the empty href can be masked by, for example, a variable that has an empty value or a function call that returns an empty value.

Something went wrong with that request. Please try again.