White-space - Property CSS

white-space

Summary of characteristics of the `white-space` property

Quick description

Defines how multiple spaces and carriage returns are restored.

Status

Standard

Applies to

A tous les éléments contenant du texte.

Usable for

HTML

Predefined values

Percentages

Not applicable.

Initial value

normal

Inherited by default

Yes.

Animation type

Discrète : during an animation, the white-space property passes from one value to another without transition.

W3C Module

CSS Text Module

References (W3C)

🡇

🡅

CSS Text Module Level 4

Document status: WD (Working Draft)

CSS Text Module Level 3

Document status: CR (Candidate Recommendation)

Cascading Style Sheets Level 2 - Revision 1 Specification

Document status: REC (Recommendation)

Cascading Style Sheets specification - Version 1

Document status: DEPR (Old specification, declared obsolete or superseded)

Syntax diagram of `white-space`.

Syntax diagram of the white-space property
The links in the diagram provide access to more details

Description of the `white-space` property.

The white-space property defines how to represent successive spaces and newlines. Traditionally, HTML ignores successive spaces and causes the automatic line breaks of the text between words. This solution allows the author to present the HTML code (indentation) without disturbing the result displayed by the browser. However, this operation can be annoying in some cases: presentation of computer code, vertical alignment of columns, etc.

By default, browsers apply the following rules to the HTML code:

Line breaks in HTML are replaced with a space.
Tabs are replaced with a space.
The successive spaces are replaced by a single space.

As we can see in the examples below, this operation is perfect for classic text but unusable for example to display computer code. The white-space property solves this problem.

Code HTML

Result displayed by the browser

div
   It is common to insert
   spaces, line breaks
⇥ or tabs to render
⇥ the code more readable.
/div

➤

It is common to insert spaces, line breaks or tabs to render the code more readable.

div
// Access control :
 ⇥ if( pwd != '' ) {
 ⇥ ⇥ exit();
 ⇥ }
/div

➤

// Access control : if( pwd != '' ) { exit(); }

New definition of `white-space` (text module level 4).

A new definition is being studied, but not yet stabilized (see Text CSS Module - Level 4). white-space will become a shorthand property to group the values of the following three properties:

white-space-collapse : allows or does not allow the removal of multiple spaces.
white-space-trim : allows or does not allow the removal of spaces at the beginning or end of the text.
text-wrap-mode : allows or not automatic line breaks.

The current values of white-space will not change but will have an equivalent in the detailed properties, according to the table below.

`white-space`	`white-space-collapse`	`text-wrap-mode`
`normal`	`collapse`	`wrap`
`pre`	`preserve`	`nowrap`
`pre-wrap`	`preserve`	`wrap`
`pre-line`	`preserve-breaks`	`wrap`

Here is a summary of the effect of the different values for white-space :

`white-space`	Line Feed in Source	Space and tab ⁽²⁾	Automatic Line Wrap ⁽³⁾	Space at the end of the line	Other separator at the end of the line
`normal`	Collapse ⁽¹⁾	Collapse	Allowed	Remove	Hang ⁽⁴⁾
`pre`	Preserved	Preserved	Forbidden	Preserved	Preserved
`nowrap`	Preserved ⁽¹⁾	Preserved	Forbidden	Remove	Hang ⁽⁴⁾
`pre-wrap`	Preserved	Preserved	Allowed	Hang ⁽⁴⁾	Hang ⁽⁴⁾
`break-spaces`	Preserved	Preserved	Allowed	Wrap ⁽⁵⁾	Wrap ⁽⁵⁾
`pre-line`	Preserved	Collapsed	Allowed	Remove	Hang ⁽⁴⁾

(1) Line breaks are replaced by a space.

(2) These are multiple spaces or tab characters that can be reduced to a single space.

(3) These are the automatic line breaks that occur when the text reaches the right margin (in latin languages).

(4) Characters may spill over into the margin. Since these are most often invisible spaces or characters, this is not a problem.

(5) Spaces or other separator characters can be returned to the beginning of the next line.

Values for `white-space`.

The following examples are all based on text written like this in the source code:

divThis   text   is   written   with   
three   spaces   in   the source   code.   
/div

white-space: normal;

Default. Successive spaces are displayed as single spaces. Automatic line breaks are based on the width of the element (when the line of text is larger than the width of the element). Line breaks in the source code of the document are replaced by a space. The br tags are respected.

This text is written with three spaces in the source code.
white-space: nowrap;

Successive spaces are displayed as single spaces.
Automatic line breaks are not performed, and the wraps in the HTML are ignored (The only line break possible is therefore the forced return with a BR tag).

This means that text can overflow to the right of the element if the lines are longer than the width of the element.

This text is written with three spaces in the source code.
white-space: pre;

Multiple spaces and line breaks are done as they appear in the HTML code.

No automatic line breaks are added. The text can therefore overflow to the right of the element. It may also not start against the left edge if there is a tab or spaces at the beginning of the line in the HTML.

This text is written with three spaces in the source code.
white-space: pre-line;

Successive spaces are displayed as single spaces. Line breaks are done as they appear in the HTML code, or based on the width of the element.

This text is written with three spaces in the source code.
white-space: pre-wrap;

The successive spaces are preserved. Automatic line breaks are based on the width of the element.

This text is written with three spaces in the source code.
white-space: break-spaces;

As with the pre-wrap value, successive spaces are preserved, and automatic line breaks are made, but break-spaces allows line breaks between successive spaces: which may causes empty lines (adjust the width of the element).

This text is written with three spaces in the source code.
white-space: initial; (normal) white-space: inherit; white-space: revert; white-space: revertLayer; white-space: unset;

Common values are presented on these pages: initial, inherit, revert, revert-layer, unset.

Animation of the `white-space` property.

The animation below goes through all the values in white-space.

This text contains multiple spaces and returns line in the code.

Simulator.

The text below has three spaces between each word and two line break, materialized by the symbol ⮐. It was entered in the HTML code like this:

p This text has been entered ⮐ with three spaces between words ⮐ and two line breaks. /p

To highlight the difference between pre-wrap and break-spaces, adjust gently the width of the element. break-spaces allows the line break between spaces: you will see spaces at the beginning of the next line, which never happens with pre-wrap that doesn't cut than after the sequences of spaces.

This text has been entered with three spaces between each word and two line break.

Browsers compatibility.

Column 1

Support for the white-space property in its original syntax (up to and including version 3).

Column 2

Support for the display property as a summary property.

Notes:

(1) Accepts values only white-space-collapse and text-wrap-mode, not white-space-trim.

white-space
property

New
values

Estimated overall support.

96%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

KaiOS Browser

Opéra Mobile

Chrome

Edge

Opéra

Safari

Safari sur IOS

Androïd Brower

Chrome pour Androïd

Firefox pour Androïd

Samsung Internet

Firefox

Baidu Browser

QQ Browser

UC Browser pour Androïd

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

`white-space` property historic.

Cascading Style Sheets specification - Version 1

First definition of the white-space property, accepting the values normal, pre and nowrap.

November 17, 1995
Working Draft.
November 12, 1996
Proposed for recommendation.
December 17, 1996
Recommendation .
September 13, 2018
Old specification, declared obsolete.
Cascading Style Sheets Level 2 - Revision 1 Specification

Adding new values for the white-space property: pre-wrap, pre-line and inherit.

November 04, 1997
Working Draft.
March 24, 1998
Proposed for recommendation.
May 11, 1998
Recommendation .
CSS Text Module Level 3

Adding break-spaces value to white-space property value.

January 27, 1999
Working Draft.
December 22, 2020
Candidate Recommendation.
CSS Text Module Level 4

Since this level of the CSS specification, white-space is a shorthand property grouping the values of white-space-collapse, text-wrap-mode properties and white-space-trim.

September 22, 2015
Working Draft.

On text management, see also.

The white-space property is described in the CSS Text Module specification, as well as everything related to text handling (alignment, spacing, hyphenation, overflow, etc.). The following properties are also included in this specification module:

Properties:

⚠

hanging-punctuation

Sets suspended punctuation (characters allowed to overflow into the margin).

hyphenate-character

Defines the character that will be used as a hyphenation mark.

⚠

hyphenate-limit-chars

Sets the minimum number of characters to allow hyphenation of a word.

⚠

hyphenate-limit-last

Defines whether hyphenation is allowed at the end of a column, page, and so on.

⚠

hyphenate-limit-lines

Sets the maximum number of successive lines ending in a hyphenation

⚠

hyphenate-limit-zone

Sets the maximum number of spaces to allow or disallow hyphenation.

hyphens

Defines whether words can be hyphenated at the end of a line. The hyphenation of the words gives a more pleasant layout but can be annoying in some cases.

letter-spacing

Sets the letter Spacing.

line-break

Defines line breaks for the CJK languages (Chinese, Japanese, Korean).

⚠

line-padding

Adds a space at the beginning and end of lines.

overflow-wrap

Word breaking for CJK languages and a few others.

tab-size

Définit la taille des caractères de tabulation.

text-align