Edit online

Tables

Tables are widely used in technical documentation. This section contains information about the CSS rules that are used to style them and how to fix some problems.

Edit online

Tables - Built-in CSS

There is a combination of CSS files that address tables:
  • [PLUGIN_DIR]/css/core/-table-html-cals.css
  • [PLUGIN_DIR]/css/print/p-tables.css
Edit online

How to Handle Wide Tables - Page Rotation

Some of the tables can have a large number of columns. In this case, the table may bleed out of the page. One solution is to use landscape pages for these tables.

Setting the attribute @orient = 'land' on the table element will force the table on a new landscape page.

Another solution is to use automatic detection of wide tables (5 or more columns):

*[class~="topic/table"] > *[class~="topic/tgroup"][cols='5'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='6'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='7'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='8'] {
    page: landscape-page;
    max-width: 100%;
    page-break-before: avoid;
}    
Note: The landscape-page page layout is defined in the [PLUGIN_DIR]css/print/p-pages-and-headers.css.

If you want to rotate the entire topic that contains the big table, use:

*[class~="topic/table"] > *[class~="topic/tgroup"][cols='5'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='6'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='7'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='8'] {
    max-width: 100%;
    table-layout:auto;
}

*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']){
      page: landscape-page;
}
Edit online

How to Fix Text Bleeding From Table Cells

Slim tables or tables that have many columns make the text from the cells be confined to a small horizontal space. Sometimes this causes long words to bleed outside the cell boundaries.

By default, the built-in CSS automatically activates the hyphenation for the text inside tables as long as your topics have the language specified.

In case the text is still bleeding outside the boundaries, you can also use the overflow-wrap property to force the word to break:
*[class ~= "topic/table"] {
  overflow-wrap: break-word;
}
Edit online

How to Avoid a Table Exceeding the Page Width

The DITA specification indicates that tables should have a fixed layout. This can be done in two different ways:
  1. Using proportional or relative measures - It includes percent values and shares values (i.e. "3*" or "12*").
  2. Using fixed measures - It includes all the values followed by units (i.e. in, pt, px, and others).

Important: Although the specification allows you to combine these values, it is highly recommend that you only use one method at a time. Combining both methods could lead to a table exceeding the page width and will make the content unreadable.
Edit online

How to Enable the Automatic Table Layout

It is possible to automatically arrange the table layout directly from the customization CSS by simply adding this:

*[class~="topic/tgroup"] {
    table-layout:auto !important;
}

This will help you to obtain a more optimal arrangement of the cells inside your table.

If you want to control which table will use this layout, you can set the @outputclass attribute on the <table> element:
<table outputclass='auto_tbl'> ... </table>
Then, in the CSS, use a rule that matches the @outputclass:
*[class~="topic/table"][outputclass='auto_tbl'] > *[class~="topic/tgroup"] {
    table-layout:auto !important;
}
Important: Make sure the tables have no column width specified.
Edit online

How to Rotate Content from a Table Cell

There are cases where you want to style the first column as a kind of table header, with vertical text.

There is an important thing to remember: you can rotate an element from a table cell, but not the cell itself. So, your DITA table cell should contain a <div> or a <p> element that will be rotated. The cell has to be marked somehow so that it can be matched from the CSS. One way is to set an @outputclass attribute on it, another will be to mark the table and then match the first entries from it.

  <row>
      ...
      <entry outputclass="rotated">
            <p>Rotated</p>
      </entry>
      ...
 </row>

In your customization CSS, use the following rule that matches the child of the entry:

*[class ~= "topic/row"] > *[class ~= "topic/entry"][outputclass ~= "rotated"] {
  width: 1em; /* This gives the table column its width. It is the height of the rotated elemnet - assuming it contains just one line. */
  padding-top: 14em; /* Increase this until the entire vertical text fits into the cell. */
}
   
*[outputclass ~= "rotated"] > * {
        transform: rotate(-90deg) !important;
        width:1em; /* This also gives the table column its width. */
        height:1em; /* This is the effective width after rotation. */
        border: 1pt solid red; /* Just for debug */
        background-color:yellow; /* Just for debug */
        hyphens:manual; /* Disable hyphenation, to force the text extend out of the small bounds - the parent rotated entry has enough padding to accomodate it. */
        padding: 0;
        margin: 0;
}

The padding and margins are set to zero to clear any space that may come from other rules. The width is required - it will become the height of the cell.

Edit online

How to Add Horizontal Lines to a Choice Table

To add horizontal lines that separate the options within a <choicetable>, you can use borders set on each of the rows. The following CSS styles the top header and the first column with some background colors. In a choice table, the first column represents the choice labels.

*[class~="task/choptionhd"],
*[class~="task/choptionhd"],
*[class~="task/chdeschd"],
*[class~="task/choption"] {
	background-color: #EEEEEE;	
	text-align: left;
}

*[class~="task/choicetable"] {
	border: 2pt solid #EEEEEE;
}

*[class~="task/choicetable"] *[class~="task/chrow"],
*[class~="task/choicetable"] *[class~="task/chhead"]{
	border-bottom: 2pt solid #EEEEEE;
} 

*[class~="task/choicetable"] *[class~="topic/stentry"] {
	border-bottom: none;
	border-right: none;
}
Note: Using the frame attribute on the choice table will make these selectors apply partially. Please make sure you are designing your customization CSS taking into account all possible values for the frame attribute.
Edit online

How to Remove the Table NN Label

For the DITA Map PDF - based on HTML5 & CSS transformation scenario, the label for a table's title is wrapped in a span element with the class: table--title-label.

<table ... >
...
<caption class="- topic/title title tablecap">
    <span class="table--title-label">Table 
		<span class="table--title-label-number">1. </span></span>
    <span class="table--title">The title of the table</span>
</caption>
...

To hide it, set its display to none:

.table--title-label {
	display:none;
}

For the direct transformation, use:

*[class ~= "topic/table"] > *[class ~= "topic/title"]:before {
  content: none;
}
Edit online

How to Center Tables

You can center the tables by using margins auto, while the table caption (title) can be centered using the text-align property:

*[class ~= "topic/table"] {
    margin-left:auto;
    margin-right:auto;
    width: 50%;
    border: 1pt solid blue;
}
*[class ~= "topic/table"] *[class ~= "topic/title"]{
    text-align:center;
}
Edit online

How to Add Stripes to a Table

To create a striped look for your tables, you can use the following CSS rules:

/* Header background and foreground */
*[class ~= "topic/table"][outputclass ~= "stripes"] > *[class ~= "topic/thead"] > *[class ~= "topic/row"]  {
    background-color: blue;
    color:white;
}

/* A default background for the entire table body */
*[class ~= "topic/table"][outputclass ~= "stripes"] > *[class ~= "topic/tbody"] {
    background-color: #eeeeee;
}

/* Color for the stripes */
*[class ~= "topic/table"][outputclass ~= "stripes"] > *[class ~= "topic/tbody"] > *[class ~= "topic/row"]:nth-child(odd) {
    background-color: cyan;
}

/* Border for the cells */
*[class ~= "topic/table"][outputclass ~= "stripes"] *[class ~= "topic/entry"]  {
    border: blue;
}
The above rules assume that tables that are to be painted with stripes are marked with an @outputclass attribute:
<table outputclass="stripes">...</table>

If you want to make all tables look the same, you can ignore this attribute and remove the [outputclass ~= "stripes"] simple selector from the above rules.

CAUTION: Applying stripes and thin cell borders can cause rendering issues in the PDF renderer on screen display devices. For more information, see How to Fix Disappearing Thin Lines or Cell Borders.