HTML http-equiv Attribute

HTML http-equiv Attribute

The HTML http-equiv attribute is used with the <meta> element to define a pragma directive that can affect how the browser processes the document. The directive is selected by http-equiv, while the accompanying content attribute supplies its value.

Syntax

The http-equiv attribute is specified on a <meta> element and is normally accompanied by the content attribute.

<meta http-equiv="directive" content="value">

For example, the refresh directive can instruct the browser to reload the current document after a specified number of seconds.

<meta http-equiv="refresh" content="300">

Attribute Values

The http-equiv attribute is an enumerated attribute. The current HTML standard defines several conforming directive values, each with a different purpose.

Elements That Use the http-equiv Attribute

The http-equiv attribute is used with the <meta> element.

When http-equiv is specified, the <meta> element also requires a content attribute containing the value for the selected directive.

Encoding Declaration

The content-type value provides an alternative way to declare the UTF-8 character encoding of an HTML document.

<meta http-equiv="content-type" content="text/html; charset=utf-8">

Modern HTML normally uses the shorter charset form instead.

<meta charset="utf-8">

A document should not contain both forms. For new HTML documents, the charset="utf-8" declaration is simpler and preferred.

Refresh and Redirect

The refresh value can instruct the browser to reload the current page after a specified number of seconds.

<meta http-equiv="refresh" content="300">

This example reloads the page after 300 seconds. A URL can also be supplied to redirect the browser to another page after the delay.

<meta http-equiv="refresh" content="5; URL=/index.html">

This example waits five seconds before navigating to /index.html. Automatic refreshes and delayed redirects should be used carefully because unexpected navigation can disrupt users, particularly people using assistive technologies.

Content Security Policy

The content-security-policy value can apply a Content Security Policy to the document.

<meta http-equiv="content-security-policy"
  content="default-src 'self'; img-src 'self' https:">

A Content Security Policy can restrict the sources from which scripts, images, styles, and other resources may be loaded. This can help reduce the risk of certain content-injection attacks.

Policies supplied through a <meta> element have limitations compared with policies delivered through the HTTP Content-Security-Policy response header. For example, some directives cannot be applied through the <meta> form.

Other http-equiv Values

The HTML standard also defines default-style and x-ua-compatible, although they have limited relevance to modern websites.

The default-style directive identifies the preferred CSS style sheet set.

<meta http-equiv="default-style" content="Preferred">

The x-ua-compatible directive was associated with Internet Explorer document modes.

<meta http-equiv="x-ua-compatible" content="IE=edge">

Modern browsers are required to ignore x-ua-compatible, so it should not be needed in new websites.

The older content-language value is non-conforming. Use the lang attribute on the <html> element to identify the document language.

<html lang="en">

http-equiv and HTTP Headers

The name http-equiv comes from the idea that some pragma directives can provide behavior related to information that may otherwise be supplied through HTTP. However, a <meta http-equiv> element is not a general replacement for an HTTP response header.

Only specifically defined http-equiv values have meaning. Arbitrary HTTP header names cannot be placed in the attribute and expected to behave like real server response headers.

When a feature can be configured through an actual HTTP response header, server-delivered headers may provide capabilities that are unavailable through the HTML <meta> form.

Common Mistakes

Do not use http-equiv="content-language" to declare the language of a document. Use the lang attribute instead.

<!-- Do not use for new HTML -->
<meta http-equiv="content-language" content="en">

<!-- Correct -->
<html lang="en">

Do not include both forms of the character encoding declaration in the same document.

<!-- Use this modern form -->
<meta charset="utf-8">

Do not assume that any HTTP header name can be used as an http-equiv value. Browsers recognize only the pragma directives defined for this attribute.

Browser Support

Baseline: Widely available indicates a feature has been supported by core browsers for at least 30 months. At this stage, the feature is considered stable and safe for most websites to use without needing to worry about compatibility issues or fallbacks, as it is supported by the vast majority of users' devices and browser versions.

The http-equiv attribute on the <meta> element is widely supported, but compatibility and behavior depend on the directive being used. Individual directives can have different browser support or restrictions.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the http-equiv Attribute

The example uses http-equiv="refresh" to reload the page after 30 seconds. Change the number in the content attribute to experiment with a different delay.

Summary

The HTML http-equiv attribute is used with the <meta> element to define a pragma directive for a document. Current directives include content-type, default-style, refresh, x-ua-compatible, and content-security-policy. The accompanying content attribute supplies the value required by the selected directive, and support or behavior can differ depending on which directive is used.