HTML hreflang Attribute

Beginner
⏱️ 6 min read
📚 Updated: Jun 2026
🎯 3 Examples
SEO & Internationalization
HTML hreflang attribute tutorial — specify language and regional targeting for multilingual SEO
Overview

What You’ll Learn

The hreflang attribute lets you tell search engines and browsers which language or region a linked page is intended for. It is essential for multilingual websites because it helps Google and other search engines show the correct localized version to each user. You will most often see it on <link rel="alternate"> tags in the document <head>, and sometimes on visible <a> language-switcher links.

01

Language Codes

ISO 639-1 (en, es).

02

Region Subtags

fr-CA, en-GB.

03

rel=alternate

SEO link pattern.

04

x-default

Global fallback URL.

05

link & a

Where it applies.

06

JavaScript

Set hreflang at runtime.

Fundamentals

Purpose of hreflang

The primary purpose of the hreflang attribute is to inform search engines about the language and regional targeting of a particular webpage. When you publish the same content in multiple languages or for different countries, search engines need a clear signal about which URL belongs to which audience.

This helps search engines deliver more relevant results to users based on their language preferences and geographic location. For example, a user searching in French from Canada should see your French Canadian page (fr-CA) rather than the English version or French pages meant for France (fr-FR).

💡
hreflang vs lang

The lang attribute on <html> describes the language of the current page’s content. hreflang describes the language of the page you are linking to in href. Use both together on multilingual sites.

Foundation

📝 Syntax

Add hreflang alongside href on a <link> or <a> element. For SEO, place alternate-language links in the document head:

hreflang.html
<link rel="alternate" hreflang="en" href="https://example.com/page">
<link rel="alternate" hreflang="es" href="https://example.com/page-es">

Syntax Rules

  • Valid on <link> and <a> elements that include an href attribute.
  • For SEO, use rel="alternate" on <link> elements in the <head>.
  • Values follow BCP 47 language tags: a two-letter language code (ISO 639-1), optionally followed by a region (ISO 3166-1), e.g. en, fr-CA.
  • Use x-default for a fallback page when no other language or region matches.
  • Each language version should link to all alternates, including itself (reciprocal annotations).
  • Use absolute URLs in href for hreflang annotations when possible.
Reference

💎 Values

The hreflang attribute accepts language codes and optional region subcodes to define language and regional targeting:

  • hreflang="en" — English (any region).
  • hreflang="es" — Spanish (any region).
  • hreflang="fr-CA" — French as used in Canada.
  • hreflang="en-GB" — English as used in the United Kingdom.
  • hreflang="x-default" — Fallback page for users whose language or region does not match any other alternate.

These values help search engines understand the linguistic and regional context of the linked content. Follow the ISO 639-1 standard for language codes and ISO 3166-1 for region codes.

hreflang-values.html
<!-- Language only -->
<link rel="alternate" hreflang="de" href="https://example.com/de/">

<!-- Language + region -->
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/">

<!-- Global fallback -->
<link rel="alternate" hreflang="x-default" href="https://example.com/">
Cheat Sheet

⚡ Quick Reference

Use Casehreflang ValueNotes
English pageenLanguage only
Spanish pageesLanguage only
French (Canada)fr-CALanguage + region
Fallback / pickerx-defaultWhen no match exists
SEO patternlink rel="alternate"In document head
Applicable elementslink, aMust have href
Scope

Applicable Elements

ElementSupported?Notes
<link rel="alternate" href="...">YesPrimary SEO use in <head>
<a href="...">YesLanguage switcher links; less common for SEO than <link>
<link rel="stylesheet">Nohreflang is for alternate page versions, not stylesheets
<input>, <form>NoNot valid on form controls
Hands-On

Examples Gallery

Alternate links for SEO, a full multilingual head block with x-default, and dynamic hreflang values with JavaScript.

👀 Live Preview

Visible language switcher links with hreflang on anchor elements:

Each link’s hreflang tells search engines the language of the destination page. Use descriptive link text so users know which version they are choosing.

Example — Alternate Language Links

Two alternative versions of a page—one for English speakers and one for Spanish speakers:

hreflang.html
<head>
  <link rel="alternate" href="https://example.com/page" hreflang="en">
  <link rel="alternate" href="https://example.com/page-es" hreflang="es">
</head>
Try It Yourself

How It Works

In this example, the hreflang attribute specifies the language targeting for each alternate URL. Search engines read these annotations to understand that the English page and Spanish page are equivalent content in different languages.

Example — Multilingual Set with x-default

A complete set of alternates including a global fallback page:

hreflang-set.html
<head>
  <link rel="alternate" hreflang="x-default" href="https://example.com/">
  <link rel="alternate" hreflang="en" href="https://example.com/en/">
  <link rel="alternate" hreflang="fr-CA" href="https://example.com/fr-ca/">
  <link rel="alternate" hreflang="de" href="https://example.com/de/">
</head>
Try It Yourself

How It Works

Every language version should list all alternates, including itself. The x-default entry points to a page for users whose language is not listed—often a language picker or global homepage.

Dynamic Values with JavaScript

You can dynamically set the hreflang attribute using JavaScript when dealing with multilingual or dynamically generated content:

dynamic-hreflang.html
<a id="dynamicLink" href="https://example.com/fr/">Version française</a>

<script>
  document.getElementById("dynamicLink").hreflang = "fr";
</script>
Try It Yourself

How It Works

In this script, the hreflang attribute is dynamically set to fr for a link with the id dynamicLink. This is useful when language targeting needs to change based on user interactions, A/B tests, or content loaded from an API. You can also use setAttribute("hreflang", "fr").

A11y

♿ Accessibility

  • Use clear language labels — Visible language switcher links should name the language in plain text (e.g. “Español”, not just “ES”) so all users understand the choice.
  • Do not rely on flags alone — Country flags do not map cleanly to languages; combine flags with text labels if you use them at all.
  • Mark the current page — Indicate which language version the user is viewing with aria-current="page" on the active switcher link.
  • Pair with lang — Set lang on <html> for the page content language; use hreflang on links to alternate versions.
  • Keep switchers keyboard accessible — Language links must be focusable and operable with Enter, like any other hyperlink.

🧠 How hreflang Works

1

Author adds alternate links

Each language URL gets hreflang and href.

Markup
2

Search engine crawls pages

Google reads reciprocal hreflang annotations.

SEO
3

User searches in their language

Engine matches locale to the correct alternate URL.

Discovery
=

Right language, right audience

Users find content in their language; you avoid duplicate-content confusion.

Compatibility

Browser Support

The hreflang attribute is supported in all modern browsers on <link> and <a> elements. Its primary consumer is search engines rather than visual browser behavior—users do not see a different UI when hreflang is present.

✓ HTML5 · Fully supported

Universal hreflang support

All major browsers parse hreflang on links and anchors. Search engines rely on it for international SEO.

99% Browser support
Google Chrome Fully supported
Full support
Mozilla Firefox Fully supported
Full support
Apple Safari Fully supported
Full support
Microsoft Edge Fully supported
Full support
Internet Explorer IE 11 supported
Full support
Opera Fully supported
Full support
hreflang attribute 99% supported

Bottom line: Use hreflang confidently for multilingual SEO; validate annotations with Google Search Console or similar tools.

Pro Tips

💡 Best Practices

✅ Do

  • Use hreflang consistently across all language versions of your content
  • Follow ISO 639-1 language codes and ISO 3166-1 region codes
  • Include reciprocal links on every alternate page
  • Add x-default when you have a global fallback page
  • Test with Google Search Console international targeting reports

❌ Don’t

  • Mix up hreflang (linked page language) and lang (current page language)
  • Point all alternates to the same URL with different codes
  • Skip self-referencing hreflang on each language version
  • Use invalid or made-up language codes
  • Rely on visible switcher links alone without head annotations for SEO
Wrap Up

Conclusion

The hreflang attribute is a valuable tool for web developers aiming to provide a better experience for multilingual audiences. By accurately specifying language and regional targeting, you can enhance the discoverability and relevance of your content in search engine results.

Remember to use appropriate ISO language and region codes, keep annotations reciprocal across all versions, and pair visible language switchers with proper <link rel="alternate"> tags in the head.

View Examples Gallery Try alternate links example
Summary

Key Takeaways

Knowledge Unlocked

Five truths every developer should know about hreflang

Bookmark these before launching a multilingual site.

5
Core concepts
🌐 01

SEO Signal

Tells search engines which URL matches which language.

Purpose
📝 02

ISO Codes

en, es, fr-CA

Values
🔗 03

rel=alternate

Head link pattern

Syntax
⚙️ 04

Reciprocal

Every version links to all

SEO
🎯 05

x-default

Global fallback URL

Fallback
🎯 You’re ready to build multilingual sites with proper language targeting
Review Quick Reference →

❓ Frequently Asked Questions

It specifies the language and optional regional targeting of the page linked in href. Search engines use it to show the correct localized version to users in different countries.
<link rel="alternate"> in the document head (primary SEO use) and <a> anchor elements for visible language switchers. Both require an href attribute.
lang on <html> describes the language of the current page’s content. hreflang describes the language of the page you are linking to.
x-default is a special value for a fallback page when no other language or region matches the user—commonly a language picker or global homepage.
Yes. Assign linkElement.hreflang = "fr" or use setAttribute("hreflang", "fr") on <link> or <a> elements at runtime.
Yes in all modern browsers. Its main effect is on search engine indexing rather than visible browser UI.

Build better multilingual sites

Practice the hreflang attribute with alternate language links in the Try It editor.

Try alternate links example →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

5 people found this page helpful

HTML href Attribute HTML hspace Attribute