4 ways to control page breaks within tables and table styles (for developers)

The Microsoft Word object model has four settings that control page breaks in tables and table styles:

• In a table style: .AllowBreakAcrossPage
• In a table: .AllowBreakAcrossPages
• In a table or table style: .AllowPageBreaks
• In a various places: .KeepWithNext

This page describes my observations about how these four settings work.

In a table style: prevent or allow page breaks within rows (.AllowBreakAcrossPage )

What it does

The .AllowBreakAcrossPage property applies to the Table of a table style. It controls the behaviour of individual rows, not the whole table. It determines whether the individual rows in a table may break across a page. But this is a property of the table style, not individual rows. So it applies to all rows in the table.

As far as I can see, there is no way to set this property from the user interface. You can only do it in code. However, in the user interface, you can override the setting for one individual row in a table to which this table style has been applied.

This is actually a very useful feature. In most tables I create, I don't want any rows to break across a page. Setting this property on the table style tells Word to do just what I want. And I can use the user interface to allow an individual row to break across a page if I need to.

As far as I can see, you can't use this property to define a table style such that some rows will break and others won't. But we can achieve the same thing using .KeepWithNext. See below.

Default value

If I create a new table style, I observe that rows break across the page. So it seems like the default for .AllowBreakAcrossPage is True. The documentation says that this property returns a Long (not a Boolean), and that the default value is True. That sounds right, but it isn't. In Word-land, True is -1. But a newly-created style returns a value of 1 (not -1) for this property.

Reading the property

For a newly-created style, the default value is 1. Here is some sample VBA code from the immediate window:

?ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = True ' returns False
?ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = False ' returns False

Subsequently interrogating the value of .AllowBreakAcrossPage is also tricky. If I set the value to .True, the return value is 1 (which is not what you'd expect), and Word denies that the value is .True. If I set the value to .False, the return value is 0 (which is kind of what you'd expect) and Word acknowledges that the value is .False.

Setting the property

This works quite reliably:

 ActiveDocument.Styles("MyTableStyle").Table.AllowBreakAcrossPage = True

How to use this property

• We can set the value reliably using True or False or 1 ("true") or 0 (False).
• To read the property value, we must assume that the only valid values are 1 (ie "true") and 0 (False).

As far as I can see, there is no way to set this property in the user interface.

In a table: prevent or allow page breaks within specified rows  (.AllowBreakAcrossPages)

What it does

This property applies to a real, live table. It does not apply to a table style.

Table.Rows.AllowBreakAcrossPages or Table.Rows(n).AllowBreakAcrossPages applies to an individual Row or all the .Rows of a table. It determines whether the row(s) may break across a page. This is the setting controlled in the user interface in the Table Properties dialog box, on the Row tab.

Setting the property

This property works quite reliably. For example:

ActiveDocument.Tables(1).Rows(2).AllowBreakAcrossPages = False

Note that individual rows retain the value of their .AllowBreakAcrossPages property, even if you change the underlying table style's .Table.AllowBreakAcrossPage property. 

Reading the property

This property reliably returns True or False, just as you'd expect.

In a table or a table style: keep the whole table on one page (.AllowPageBreaks)

This property does not work, and is effectively unusable.

What it does

This property applies to a table or a table style using Table.AllowPageBreaks or Style.Table.AllowPageBreaks.

It is supposed to work like this:

• If, given paper size, margins, fonts and so on, the whole table could fit on one page, and this property is True, then Word will pop the whole table over to the next page, and keep the whole table on one page.
• If the whole table could fit on one page, and this property is False, then Word will split the table across two pages, with rows breaking according to the .AllowBreakAcrossPage and .AllowBreakAcrossPages settings.
• If the table would not fit on one page, then Word will, not unreasonably, split the table across two or more pages regardless of the setting of .AllowPageBreaks.

As far as I can see, you can only set this property in code. There is no way to set this property from the user interface. For the classic workaround in the user interface, see Keeping a table together on one page.

Default value

Microsoft's object model documentation says that this is a Boolean. And indeed, if you query the property on a newly-created table style or table, Word will tell you that the value is True. But it isn't. The default value is actually 1, not True.

Setting the property

You can set the property in the normal way:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True

But, this property doesn't work. That is, the table will not be kept on one page.

• In Word 2003, it will appear to work, but once you save the file and re-open it, it stops working.
• In Word 2007, it does not appear to do anything.
• In Word 2010, it does not appear to do anything. In Word 2010, Microsoft's object model help says that the AllowPageBreaks property is 'Hidden' and that 'Hidden' means "The member has been deprecated and is not recommended for use in code."

Reading the property

If you set the value to True, Word will then deny that you have so set it. The following, from the Immediate pane in the VBE, is clearly crazy:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks
True
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = True
False

When Word reports that the value is True, the value is actually 1.

If you set the value to False, then Word behaves rather better:

ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = False
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks
False
?ActiveDocument.Styles("MyTableStyle").Table.AllowPageBreaks = False
True

How to use this property, given the bugs

We can't use this property because it doesn't work.

.KeepWithNext

"Keep with next" means "keep this paragraph on the same page as the next paragraph".

The .KeepWithNext property applies to the .Paragraphs collection, a .Paragraph object and the .ParagraphFormat object.

Thus, it can be applied to one or more real paragraphs (using the .Paragraphs collection or a .Paragraph object) or to a paragraph or table style (using the style's .ParagraphFormat property).

.KeepWithNext is used extensively in defining paragraph styles. By default, the heading styles have .KeepWithNext = True so as to prevent a heading at the bottom of the page, and its subsequent text at the top of the following page.

In tables, .KeepWithNext works a little differently. If any paragraph in a row of a table is marked KeepWithNext = True, then that row will always appear on the same page as the first paragraph in the following row. If that following row is marked so as not to break across a page, then the KeepWithNext setting has the effect of keeping that row on the same page as the whole of the following row.

In theory, we can set a table style's .ParagraphFormat to KeepWithNext. For example:

ActiveDocument.Styles("MyTableStyle").ParagraphFormat.KeepWithNext = True

But I can't see any effect of doing this. It doesn't seem to work at all.

But .KeepWithNext does have interesting, if inconsistent, effects when applied to just part of a table style using one of the style's .Conditions.

sty.Table.Condition(wdFirstRow) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdLastRow) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdFirstColumn) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdNWCell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdNECell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdSWCell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdSECell) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdEvenRowBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdEvenColumnBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdOddRowBanding) _
.ParagraphFormat.KeepWithNext = True

sty.Table.Condition(wdOddColumnBanding) _
.ParagraphFormat.KeepWithNext = True