W3cubDocs

/HTML

<a>

The <a> (or anchor element) creates a hyperlink to other web pages, files, locations within the same page, email addresses, or any other URL.

Content categories Flow content, phrasing content, interactive content, palpable content.
Permitted content Transparent, containing either flow content (excluding interactive content) or phrasing content.
Tag omission None, both the starting and ending tag are mandatory.
Permitted parents Any element that accepts phrasing content, or any element that accepts flow content, but always excluding <a> elements (according to the logical principle of symmetry, if <a> tag, as a parent, can not have interactive content, then the same <a> content can not have <a> tag as its parent).
Permitted ARIA roles button, checkbox, menuitem, menuitemcheckbox, menuitemradio, option, radio, switch, tab, treeitem
DOM interface HTMLAnchorElement

Attributes

This element's attributes include the global attributes.

download HTML5
This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want). There are no restrictions on allowed values, though / and \ are converted to underscores. Most file systems limit some punctuation in file names, and browsers will adjust the suggested name accordingly.
Notes:
  • This attribute only works for same-origin URLs.
  • This attribute can be used with blob: URLs and data: URLs to download content generated by JavaScript, such as pictures created in an image-editor Web app.
  • If the HTTP header Content-Disposition: gives a different filename than this attribute, the HTTP header takes priority over this attribute.
  • If Content-Disposition: is set to inline, Firefox prioritizes Content-Disposition, like the filename case, while Chrome prioritizes the download attribute.
href
Contains a URL or a URL fragment that the hyperlink points to.
A URL fragment is a name preceded by a hash mark (#), which specifies an internal target location (an ID of an HTML element) within the current document. URLs are not restricted to Web (HTTP)-based documents, but can use any protocol supported by the browser. For example, file:, ftp:, and mailto: work in most browsers.
This attribute may be omitted (as of HTML5) to create a placeholder link. A placeholder link resembles a traditional hyperlink, but does not lead anywhere.

Note: You can use href="#top" or the empty fragment href="#" to link to the top of the current page. This behavior is specified by HTML5.

hreflang
This attribute indicates the human language of the linked resource. It is purely advisory, with no built-in functionality. Allowed values are determined by BCP47.
ping
Contains a space-separated list of URLs to which, when the hyperlink is followed, POST requests with the body PING will be sent by the browser (in the background). Typically used for tracking.
referrerpolicy
Indicates which referrer to send when fetching the URL:
  • 'no-referrer' means the Referer: header will not be sent.
  • 'no-referrer-when-downgrade' means no Referer: header will be sent when navigating to an origin without HTTPS. This is the default behavior.
  • 'origin' means the referrer will be the origin of the page, not including information after the domain.
  • 'origin-when-cross-origin' meaning that navigations to other origins will be limited to the scheme, the host and the port, while navigations on the same origin will include the referrer's path.
  • 'unsafe-url' means the referrer will include the origin and path, but not the fragment, password, or username. This is unsafe because it can leak data from secure URLs to insecure ones.
rel
Specifies the relationship of the target object to the link object. The value is a space-separated list of link types.
target
Specifies where to display the linked URL. It is a name of, or keyword for, a browsing context: a tab, window, or <iframe>. The following keywords have special meanings:
  • _self: Load the URL into the same browsing context as the current one. This is the default behavior.
  • _blank: Load the URL into a new browsing context. This is usually a tab, but users can configure browsers to use new windows instead.
  • _parent: Load the URL into the parent browsing context of the current one. If there is no parent, this behaves the same way as _self.
  • _top: Load the URL into the top-level browsing context (that is, the "highest" browsing context that is an ancestor of the current one, and has no parent). If there is no parent, this behaves the same way as _self.

Note: When using target, consider adding rel="noopener noreferrer" to avoid exploitation of the window.opener API.

type
Specifies the media type in the form of a MIME type for the linked URL. It is purely advisory, with no built-in functionality.

Obsolete

charset Obsolete since HTML5
This attribute defined the character encoding of the linked URL. The value should be a space- and/or comma-delimited list of character sets defined in RFC 2045. The default value is ISO-8859-1.

Usage note: This attribute is obsolete in HTML5 and should not be used by authors. To achieve its effect, use the HTTP Content-Type: header on the linked URL.

coords HTML 4 only, Obsolete since HTML5
For use with the below shape attribute, this attribute used a comma-separated list of numbers to define the coordinates of the link on the page.
name HTML 4 only, Obsolete since HTML5
This attribute was required for anchors defining a possible target location within a page. In HTML 4.01, id and name could be used simultaneously on a <a> element as long as they have identical values.

Usage note: This attribute is obsolete in HTML5, use the global attribute id instead.

rev HTML 4 only, Obsolete since HTML5
This attribute specified a reverse link, the inverse relationship of the rel attribute. It was deprecated for being very confusing.
shape HTML 4 only, Obsolete since HTML5
This attribute was used to define a region for hyperlinks to create an image map. The values are circle, default, polygon, and rect. The format of the coords attribute depends on the value of shape. For circle, the value is x,y,r where x and y are the pixel coordinates for the center of the circle and r is the radius value in pixels. For rect, the coords attribute should be x,y,w,h. The x,y values define the upper-left-hand corner of the rectangle, while w and h define the width and height respectively. A value of polygon for shape requires x1,y1,x2,y2,... values for coords. Each of the x,y pairs defines a point in the polygon, with successive points being joined by straight lines and the last point joined to the first. The value default for shape requires that the entire enclosed area, typically an image, be used.
Note: Use the usemap attribute for the <img> element and the associated <map> element to define hotspots instead of the shape attribute.

Examples

Linking to an external location

<!-- anchor linking to external file -->
<a href="https://www.mozilla.com/">
External Link
</a>

Result

External Link

Linking to another section on the same page

<!-- links to element on this page with id="attr-href" -->
<a href="#attr-href">
Description of Same-Page Links
</a> 

Result

Description of Same Page Links

Creating a clickable image

This example uses an image to link to the MDN home page. The home page will open in a new browsing context, that is, a new page or a new tab.

<a href="https://developer.mozilla.org/en-US/" target="_blank">
  <img src="https://mdn.mozillademos.org/files/6851/mdn_logo.png"
       alt="MDN logo" />
</a>

Result

It's common to create links that open in the user's email program to allow them to send a new message. This is done with a mailto: link. Here's a simple example:

<a href="mailto:[email protected]">Send email to nowhere</a>

Result

Send email to nowhere

For additional details about the mailto URL scheme, such as including the subject, body, or other predetermined content, see Email links or RFC 6068.

Offering phone links is helpful for users viewing web documents and laptops connected to phones.

<a href="tel:+491570156">+49 157 0156</a>

For additional details about the tel URL scheme, see RFC 3966.

Using the download attribute to save a <canvas> as a PNG

If you want to let users download an HTML <canvas> element as an image, you can create a link with a download attribute and the canvas data as a file URL:

var link = document.createElement('a');
link.textContent = 'download image';

link.addEventListener('click', function(ev) {
    link.href = canvas.toDataURL();
    link.download = "mypainting.png";
}, false);

document.body.appendChild(link);

You can see this in action at jsfiddle.net/codepo8/V6ufG/2/.

Notes

HTML 3.2 defines only the name, href, rel, rev, and title attributes.

Accessibility recommendations

Anchor tags are often abused with the onclick event to create pseudo-buttons by setting href to "#" or "javascript:void(0)" to prevent the page from refreshing. These values cause unexpected behavior when copying/dragging links, opening links in a new tabs/windows, bookmarking, and when JavaScript is still downloading, errors out, or is disabled. This also conveys incorrect semantics to assistive technologies (e.g., screen readers). In these cases, it is recommended to use a <button> instead. In general you should only use an anchor for navigation using a proper URL.

Clicking and focus

Whether clicking on an <a> causes it to become focused varies by browser and OS.

Does clicking on an <a> give it focus?
Desktop Browsers Windows 8.1 OS X 10.9
Firefox 30.0 Yes Yes
Chrome ≥39
(Chromium bug 388666)
Yes Yes
Safari 7.0.5 N/A Only when it has a tabindex
Internet Explorer 11 Yes N/A
Presto (Opera 12) Yes Yes
Does tapping on an <a> give it focus?
Mobile Browsers iOS 7.1.2 Android 4.4.4
Safari Mobile Only when it has a tabindex N/A
Chrome 35 ??? Only when it has a tabindex

Specifications

Browser compatibility

Feature Chrome Edge Firefox Internet Explorer Opera Safari
Basic support Yes Yes Yes1 Yes Yes Yes
charset Yes Yes Yes Yes Yes Yes
coords No No Yes — 582 No No No
download 14 133 20 No 15 10.1
href Yes Yes Yes Yes Yes Yes
hreflang Yes Yes Yes Yes Yes Yes
name Yes Yes Yes Yes Yes Yes
ping Yes No Yes4 No Yes No
referrerpolicy 51 No 50 No No No
rel Yes Yes Yes Yes Yes Yes
rev Yes Yes Yes Yes Yes Yes
shape No No Yes — 582 No No No
target Yes Yes Yes Yes Yes Yes
type Yes Yes Yes Yes Yes Yes
Feature Android webview Chrome for Android Edge mobile Firefox for Android IE mobile Opera Android iOS Safari
Basic support Yes Yes Yes Yes1 Yes Yes Yes
charset Yes Yes Yes Yes Yes Yes Yes
coords No No No Yes — 582 No No No
download ? ? Yes 20 No ? No
href Yes Yes Yes Yes Yes Yes Yes
hreflang Yes Yes Yes Yes Yes Yes Yes
name Yes Yes Yes Yes Yes Yes Yes
ping ? ? No Yes4 No ? No
referrerpolicy 51 51 No 50 No No No
rel Yes Yes Yes Yes Yes Yes Yes
rev Yes Yes Yes Yes Yes Yes Yes
shape No No No Yes — 582 No No No
target Yes Yes Yes Yes Yes Yes Yes
type Yes Yes Yes Yes Yes Yes Yes

1. Starting with Firefox 41, <a> without href attribute is no longer classified as interactive content: clicking it inside <label> will activate labelled content (bug 1167816).

2. You can no longer nest an <a> element inside a <map> element to create a hotspot region — coords and shape attribute support removed.

3. Until Edge 14 (build 14357), attempting to download data URIs caused Edge to crash (bug 7160092).

4. This feature is behind the browser.send_pings preference (needs to be set to true). To change preferences in Firefox, visit about:config.

See also

© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a