Okay, first things first. Why “hCard”? The name is derived from its inspiration, the IETF-standardized vCard format. You may not know of the vCard, but the chances are that you’re using software that’s based on the vCard standard: contacts in Microsoft Outlook are vCards, as are the contacts in Apple’s Address Book application; it’s also likely that the contacts in your mobile phone are actually stored in vCard format, which is what makes it easy for you to bluetooth your contacts across to other phones made by different manufacturers—they, too, use the vCard format. If you drag a contact from your Outlook address book onto your desktop, you’ll see that the file extension is .vcf. There are no prizes for guessing what that’s short for! hCard is an HTML (emphasis on the H) adaptation of the vCard format.

Regardless of how your address book or email contacts software displays the contact information, the underlying makeup of the vcard is based on the standard, and if you were to export one of your contacts, save it as a .vcf format, and then open it in a text editor, you’d see something like this:

FN:MegaCorp International
ORG:MegaCorp International;
TITLE:Senior Pen Pusher
TEL;WORK:0101 0202 2000
ADR;WORK:;;1 Gigantic Complex;Megacity;Urbania;10000;

If you wanted to specify contact details for this person on a web site, you couldn’t use basic HTML/XHTML to do so. However, you can use hCard to mark up your HTML, reusing the naming conventions set out in the vCard format. The address details above could be expressed as follows:

<div class="vcard">
 <span class="fn"><span class="given-name">Joe</span>
 <span class="family-name">Bloggs</span></span>,
 <span class="title">Senior Pen Pusher</span>,
 <div class="org">MegaCorp International</div>
 <div class="adr">
  <div class="street-address">1 Gigantic Complex</div>
  <span class="locality">Megacity</span>,
  <span class="region">Urbania</span>
  <span class="postal-code">10000</span>
 <div>Tel: <span class="tel">0101 0202 2000</span></div>
 <span class="email">joe@megacorpinternational.com</span></div>

You’ll note that there’s nothing here that would cause the HTML to be invalid—it’s merely a collection of div and span elements with class attributes, the values of which tally with the vCard naming conventions. You could use other kinds of HTML as you see fit, perhaps using a table, or a list, depending on the usage. As long as you’re using valid HTML in the right way, you can add the class names to give the content some meaning. For example, this table-formatted contact would also be perfectly acceptable as an hCard:

<table class="vcard">
  <th scope="row">Name</th>
  <td scope="row" class="fn n">
  <span class="given-name">Joe</span>
  <span class="family-name">Bloggs</span>
  <th scope="row">Company</th>
  <td class="org">MegaCorp International</td>
  <th scope="row">Address</th>
  <td class="adr">
  <span class="street-address">1 Gigantic Complex</span>,
  <span class="locality">Megacity</span>,
  <span class="region">Urbania</span>
  <span class="postal-code">10000</span>
  <th scope="row">Telephone</th>
  <td class="tel">0101 0202 2000</td>
  <th scope="row">Email</th>
  <td class="email">joe@megacorpinternational.com</td>

The examples shown above don’t make use of all the available class attribute values. In fact, there are quite a lot available for use, as the following list reveals. The values shown inside the parentheses are sub-properties that you’d nest inside the parent property—the value that immediately precedes the section, for instance, "family-name", and "given-name" are subproperties of "n", which is short for name. Note that "fn" is short for formatted name:

  • "fn", "n" ("family-name", "given-name", "additional-name", "honorific-prefix", "honorific-suffix"), "nickname", "sort-string"
  • "url", "email" ("type", "value"), "tel" ("type", "value")
  • "adr" ("post-office-box", "extended-address", "street-address", "locality", "region", "postal-code", "country-name", "type", "value"), "label"
  • "geo" ("latitude", "longitude"), "tz"
  • "photo", "logo", "sound", "bday"
  • "title", "role", "org" ("organization-name", "organisation-unit")
  • "category", "note"
  • "class", "key", "mailer", "uid", "rev"

As you can see, there’s quite a lot of information that you can use to markup contact details in a very rich and semantic manner.


Here’s a very basic contact showing just a name and telephone number:

<div class="vcard">
 <span class="fn">
  <span class="given-name">Joe</span>
  <span class="family-name">Bloggs</span>
 <span class="tel">0101 0202 2000</span>

What's the Benefit of Using hCard?

You may still be wondering why it’s worth the effort to mark up contacts using the hCard schema, even with the Google example that I demonstrated earlier. Perhaps your reason for thinking this is that it requires the user to have a special toolbar or extension installed in the web browser, which automatically reduces the number of people that are likely to benefit from this change. This alone may put you off bothering to use hCard (or other Microformats, for that matter), but bear the following in mind:

  • RSS feeds were once available only to people who installed special toolbars or extensions (or who used web-based services) to subscribe to web site feeds in RSS or ATOM format. Now, though, all current browsers, including IE7, Firefox, and Safari, come with RSS enabled by default, and feeds are made available on almost all blogs and many mainstream news sites. So, just like RSS, Microformats will enjoy native support in forthcoming browser versions, including those of Firefox and IE8. Bill Gates is on the record as saying that “we need more Microformats,” and if he is personally saying that, you can bet your stocks in Microsoft that they’ll be supported in IE8.
  • Even without an extra toolbar or extension, you can make this contact information easy to download and store on the user’s machine. Create a link that invites users to “Download this information as a vCard contact that you can add to Outlook, your Address Book,” for example, point that link to http://feeds.technorati.com/contacts/, and append the URL of the page to that link. A vcard will be generated on the fly and offered as a download, as shown in Figure 1. What’s happening here is that the URL of the page that the link’s on is passed along to the service, which is able to scan through the page, identify the correctly marked up Microformat content, and generate a .vcf version of it.
    Figure 1. The link shown is a concatenation of the vcard creator service hosted on technorati and the referring page’s URL Link to vcard download on Technorati
    Figure 2. Clicking on the link displays a download dialog Clicking on that link prompts a download dialogue, and the resultant download can be added quickly to an address book application
  • It’s not difficult to mark up contacts using hCard. If you're worried about getting it wrong, you can easily create an hCard using the hCard creator, then adapt it as you see fit, perhaps so that data can be dynamically generated. If you have an online telephone or contacts lookup service, it would take but a few moments of development time to add the necessary markup and, in an instant, make all those contacts available in hCard format.

You can use hCard in many ways, in terms of the HTML that you choose to use to structure the content, but as long as you stick to the reserved class name values stated earlier, and apply them to the correct parts of the data, you can’t go wrong.

User-contributed notes

by lrivers
Wed, 28 Jan 2009 15:40:13 GMT

the hCard url above is incorrect. Instead, it should be: http://microformats.org/code/hcard/creator (no trailing slash).

Related Products