Understanding Styles

“Master, why doesn’t my paragraph appear with the style I specified?”
“You have come to the right page Grasshopper; read on …”

What is a style in Word?

Documents communicate better when like elements are formatted consistently. To achieve that consistency, professional document designers develop a style sheet which defines the document element types and specifies how each should be formatted. For example, perhaps body paragraphs are to be set in 9 pt Times Roman with a line height of 11 pt, justified flush left, ragged right. When these specifications are applied to each of the elements of the document, a consistent and polished look is achieved.

A style in Word is such a set of specifications that may be applied, all at once, to a document element. Word has paragraph styles, character styles, table styles, and numbering definitions. These are applied to a paragraph, a span of text, a table, and a list, respectively.

Experienced programmers will recognize styles as a level of indirection. The great thing about those is it allows you to define something once, then apply that definition many times. This saves the work of defining the same thing over an over; but more importantly it allows you to change the definition and have that change reflected in all the places you have applied it.

Why doesn’t the style I applied show up?

This is likely to show up quite a bit until I can add some fancier features to work around it, so here it is up top.

  1. When you’re working in Word, there are all these styles you can apply to things, pretty good looking ones that look all the better because you don’t have to make them yourself. Most folks never look further than the built-in styles.
  2. Although those styles show up in the UI, they’re not actually in the document you’re creating, at least not until you use it for the first time. That’s kind of a good thing. They take up room and there’s a lot of them. The file would get a little bloated if it contained all the style definitions you could use but haven’t.
  3. If you apply a style using python-docx that’s not defined in your file (in the styles.xml part if you’re curious), Word just ignores it. It doesn’t complain, it just doesn’t change how things are formatted. I’m sure there’s a good reason for this. But it can present as a bit of a puzzle if you don’t understand how Word works that way.
  4. When you use a style, Word adds it to the file. Once there, it stays. I imagine there’s a way to get rid of it, but you have to work at it. If you apply a style, delete the content you applied it to, and then save the document; the style definition stays in the saved file.

All this adds up to the following: If you want to use a style in a document you create with python-docx, the document you start with must contain the style definition. Otherwise it just won’t work. It won’t raise an exception, it just won’t work.

If you use the “default” template document, it contains the styles listed below, most of the ones you’re likely to want if you’re not designing your own. If you’re using your own starting document, you need to use each of the styles you want at least once in it. You don’t have to keep the content, but you need to apply the style to something at least once before saving the document. Creating a one-word paragraph, applying five styles to it in succession and then deleting the paragraph works fine. That’s how I got the ones below into the default template :).


style definition
A <w:style> element in the styles part of a document that explicitly defines the attributes of a style.
defined style
A style that is explicitly defined in a document. Contrast with latent style.
built-in style
One of the set of 276 pre-set styles built into Word, such as “Heading 1”. A built-in style can be either defined or latent. A built-in style that is not yet defined is known as a latent style. Both defined and latent built-in styles may appear as options in Word’s style panel and style gallery.
custom style
Also known as a user defined style, any style defined in a Word document that is not a built-in style. Note that a custom style cannot be a latent style.
latent style
A built-in style having no definition in a particular document is known as a latent style in that document. A latent style can appear as an option in the Word UI depending on the settings in the LatentStyles object for the document.
recommended style list
A list of styles that appears in the styles toolbox or panel when “Recommended” is selected from the “List:” dropdown box.
Style Gallery
The selection of example styles that appear in the ribbon of the Word UI and which may be applied by clicking on one of them.

Identifying a style

A style has three identifying properties, name, style_id, and type.

Each style’s name property is its stable, unique identifier for access purposes.

A style’s style_id is used internally to key a content object such as a paragraph to its style. However this value is generated automatically by Word and is not guaranteed to be stable across saves. In general, the style id is formed simply by removing spaces from the localized style name, however there are exceptions. Users of python-docx should generally avoid using the style id unless they are confident with the internals involved.

A style’s type is set at creation time and cannot be changed.

Built-in styles

Word comes with almost 300 so-called built-in styles like Normal, Heading 1, and List Bullet. Style definitions are stored in the styles.xml part of a .docx package, but built-in style definitions are stored in the Word application itself and are not written to styles.xml until they are actually used. This is a sensible strategy because they take up considerable room and would be largely redundant and useless overhead in every .docx file otherwise.

The fact that built-in styles are not written to the .docx package until used gives rise to the need for latent style definitions, explained below.

Style Behavior

In addition to collecting a set of formatting properties, a style has five properties that specify its behavior. This behavior is relatively simple, basically amounting to when and where the style appears in the Word or LibreOffice UI.

The key notion to understanding style behavior is the recommended list. In the style pane in Word, the user can select which list of styles they want to see. One of these is named Recommended and is known as the recommended list. All five behavior properties affect some aspect of the style’s appearance in this list and in the style gallery.

In brief, a style appears in the recommended list if its hidden property is False (the default). If a style is not hidden and its quick_style property is True, it also appears in the style gallery. If a hidden style’s unhide_when_used property is True, its hidden property is set False the first time it is used. Styles in the style lists and style gallery are sorted in priority order, then alphabetically for styles of the same priority. If a style’s locked property is True and formatting restrictions are turned on for the document, the style will not appear in any list or the style gallery and cannot be applied to content.

Latent styles

The need to specify the UI behavior of built-in styles not defined in styles.xml gives rise to the need for latent style definitions. A latent style definition is basically a stub style definition that has at most the five behavior attributes in addition to the style name. Additional space is saved by defining defaults for each of the behavior attributes, so only those that differ from the default need be defined and styles that match all defaults need no latent style definition.

Latent style definitions are specified using the w:latentStyles and w:lsdException elements appearing in styles.xml.

A latent style definition is only required for a built-in style because only a built-in style can appear in the UI without a style definition in styles.xml.

Style inheritance

A style can inherit properties from another style, somewhat similarly to how Cascading Style Sheets (CSS) works. Inheritance is specified using the base_style attribute. By basing one style on another, an inheritance hierarchy of arbitrary depth can be formed. A style having no base style inherits properties from the document defaults.

Paragraph styles in default template

  • Normal
  • Body Text
  • Body Text 2
  • Body Text 3
  • Caption
  • Heading 1
  • Heading 2
  • Heading 3
  • Heading 4
  • Heading 5
  • Heading 6
  • Heading 7
  • Heading 8
  • Heading 9
  • Intense Quote
  • List
  • List 2
  • List 3
  • List Bullet
  • List Bullet 2
  • List Bullet 3
  • List Continue
  • List Continue 2
  • List Continue 3
  • List Number
  • List Number 2
  • List Number 3
  • List Paragraph
  • Macro Text
  • No Spacing
  • Quote
  • Subtitle
  • TOCHeading
  • Title

Character styles in default template

  • Body Text Char
  • Body Text 2 Char
  • Body Text 3 Char
  • Book Title
  • Default Paragraph Font
  • Emphasis
  • Heading 1 Char
  • Heading 2 Char
  • Heading 3 Char
  • Heading 4 Char
  • Heading 5 Char
  • Heading 6 Char
  • Heading 7 Char
  • Heading 8 Char
  • Heading 9 Char
  • Intense Emphasis
  • Intense Quote Char
  • Intense Reference
  • Macro Text Char
  • Quote Char
  • Strong
  • Subtitle Char
  • Subtle Emphasis
  • Subtle Reference
  • Title Char

Table styles in default template

  • Table Normal
  • Colorful Grid
  • Colorful Grid Accent 1
  • Colorful Grid Accent 2
  • Colorful Grid Accent 3
  • Colorful Grid Accent 4
  • Colorful Grid Accent 5
  • Colorful Grid Accent 6
  • Colorful List
  • Colorful List Accent 1
  • Colorful List Accent 2
  • Colorful List Accent 3
  • Colorful List Accent 4
  • Colorful List Accent 5
  • Colorful List Accent 6
  • Colorful Shading
  • Colorful Shading Accent 1
  • Colorful Shading Accent 2
  • Colorful Shading Accent 3
  • Colorful Shading Accent 4
  • Colorful Shading Accent 5
  • Colorful Shading Accent 6
  • Dark List
  • Dark List Accent 1
  • Dark List Accent 2
  • Dark List Accent 3
  • Dark List Accent 4
  • Dark List Accent 5
  • Dark List Accent 6
  • Light Grid
  • Light Grid Accent 1
  • Light Grid Accent 2
  • Light Grid Accent 3
  • Light Grid Accent 4
  • Light Grid Accent 5
  • Light Grid Accent 6
  • Light List
  • Light List Accent 1
  • Light List Accent 2
  • Light List Accent 3
  • Light List Accent 4
  • Light List Accent 5
  • Light List Accent 6
  • Light Shading
  • Light Shading Accent 1
  • Light Shading Accent 2
  • Light Shading Accent 3
  • Light Shading Accent 4
  • Light Shading Accent 5
  • Light Shading Accent 6
  • Medium Grid 1
  • Medium Grid 1 Accent 1
  • Medium Grid 1 Accent 2
  • Medium Grid 1 Accent 3
  • Medium Grid 1 Accent 4
  • Medium Grid 1 Accent 5
  • Medium Grid 1 Accent 6
  • Medium Grid 2
  • Medium Grid 2 Accent 1
  • Medium Grid 2 Accent 2
  • Medium Grid 2 Accent 3
  • Medium Grid 2 Accent 4
  • Medium Grid 2 Accent 5
  • Medium Grid 2 Accent 6
  • Medium Grid 3
  • Medium Grid 3 Accent 1
  • Medium Grid 3 Accent 2
  • Medium Grid 3 Accent 3
  • Medium Grid 3 Accent 4
  • Medium Grid 3 Accent 5
  • Medium Grid 3 Accent 6
  • Medium List 1
  • Medium List 1 Accent 1
  • Medium List 1 Accent 2
  • Medium List 1 Accent 3
  • Medium List 1 Accent 4
  • Medium List 1 Accent 5
  • Medium List 1 Accent 6
  • Medium List 2
  • Medium List 2 Accent 1
  • Medium List 2 Accent 2
  • Medium List 2 Accent 3
  • Medium List 2 Accent 4
  • Medium List 2 Accent 5
  • Medium List 2 Accent 6
  • Medium Shading 1
  • Medium Shading 1 Accent 1
  • Medium Shading 1 Accent 2
  • Medium Shading 1 Accent 3
  • Medium Shading 1 Accent 4
  • Medium Shading 1 Accent 5
  • Medium Shading 1 Accent 6
  • Medium Shading 2
  • Medium Shading 2 Accent 1
  • Medium Shading 2 Accent 2
  • Medium Shading 2 Accent 3
  • Medium Shading 2 Accent 4
  • Medium Shading 2 Accent 5
  • Medium Shading 2 Accent 6
  • Table Grid