Package com.vaadin.flow.component.html

Class Table

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.HtmlComponent
com.vaadin.flow.component.html.Table
All Implemented Interfaces:
AttachNotifier, ClickNotifier<Table>, DetachNotifier, HasAriaLabel, HasElement, HasSize, HasStyle, Serializable
@NullMarked @Tag("table") public class Table extends HtmlComponent implements ClickNotifier<Table>, HasAriaLabel
Component representing a <table> element.

Unlike the deprecated NativeTable, this component does not extend HtmlContainer, so it has no generic add(Component). A <table> may only contain a <caption>, <colgroup>, <thead>, <tbody> and <tfoot>, and those are reached through the accessors below, which also keep them in the order the WHATWG HTML specification requires.

Most code never has to name a section. addRow(), addRowWithHeader(String, String...), addHeaderRow() and addFooterRow() create the enclosing <tbody>, <thead> or <tfoot> on demand, and getHeaderRows(), getBodyRows(), getFooterRows(), getAllRows() and removeRow(TableRow) read and remove rows without one either. This mirrors the DOM, where inserting a row into a table materialises the missing row group by itself. Reach for getHead() and friends only when you need to address a section as a whole ? to style it, or to hand it to bindChildren.

When InitParameters.THEMED_HTML is enabled, the Aura and Lumo themes apply their styles to the native HTML elements of the application, and so to a table. A single element is left to the browser with addClassName(Constants.UNTHEMED_HTML_CLASS_NAME), or styled on its own, without the property, with addClassName(Constants.THEMED_HTML_CLASS_NAME); see Constants.

Since:
25.3
See Also:

  • Constructor Details

    • Table

      public Table()
      Creates a new empty table.

  • Method Details

    • getCaption

      public TableCaption getCaption()
      Returns this table's caption, creating one if the table has none. Reading through this accessor therefore has a side effect; use hasCaption() or getCaptionText() to inspect the table without adding a caption to it.
      Returns:
      the table's <caption>.

    • hasCaption

      public boolean hasCaption()
      Reports whether this table already has a <caption>. Unlike getCaption(), this does not create one.
      Returns:
      true if the table has a caption.

    • getCaptionText

      public @Nullable String getCaptionText()
      Returns the text content of this table's caption, or null if the table has no caption or the caption holds something other than text. Unlike getCaption(), this does not create one.

      A caption assembled from components has no faithful text representation, and reporting whichever text nodes happen to sit around those components would be misleading, so null is returned instead. Use hasCaption() to tell a table with no caption from one whose caption holds markup.

      Returns:
      the caption text, or null if there is none to report.

    • setCaptionText

      public void setCaptionText(@Nullable String text)
      Sets the text content of this table's caption, creating the caption if the table has none.

      Passing null removes the caption, as setCaption(TableCaption) does, so that whatever getCaptionText() reports can be handed straight back.

      Parameters:
      text - the caption text, or null to remove the caption.

    • setCaption

      public void setCaption(@Nullable TableCaption caption)
      Puts the given caption on this table, replacing the one it already has, if any.
      Parameters:
      caption - the caption to use, or null to remove the one the table has.

    • addCaption

      public TableCaption addCaption(Component... components)
      Appends the given components to this table's caption, creating it if none exists yet. Useful for richer captions containing inline markup.
      Parameters:
      components - the components to append.
      Returns:
      the caption.

    • addCaption

      public TableCaption addCaption(List<? extends Component> components)
      List equivalent of addCaption(Component...).
      Parameters:
      components - the components to append.
      Returns:
      the caption.

    • removeCaption

      public void removeCaption()
      Removes this table's caption, if it has one.

    • addColumnGroup

      public TableColumnGroup addColumnGroup()
      Appends a new empty <colgroup> to this table, after the caption and any column groups it already has, and before the <thead>.
      Returns:
      the new column group.

    • addColumnGroup

      public TableColumnGroup addColumnGroup(TableColumnGroup group)
      Appends the given <colgroup> to this table.
      Parameters:
      group - the column group to add.
      Returns:
      the given group, for chaining.

    • addColumnGroup

      public TableColumnGroup addColumnGroup(TableColumn... columns)
      Appends a new <colgroup> holding the given columns to this table.
      Parameters:
      columns - the columns the new group should hold.
      Returns:
      the new column group.

    • addColumnGroup

      public TableColumnGroup addColumnGroup(List<? extends TableColumn> columns)
      List equivalent of addColumnGroup(TableColumn...).
      Parameters:
      columns - the columns the new group should hold.
      Returns:
      the new column group.

    • getColumnGroups

      public List<TableColumnGroup> getColumnGroups()
      Returns the column groups of this table, in document order.
      Returns:
      the table's <colgroup> elements.

    • removeColumnGroup

      public void removeColumnGroup(TableColumnGroup group)
      Removes the given column group from this table.
      Parameters:
      group - the column group to remove.

    • getHead

      public TableHead getHead()
      Returns this table's <thead>, creating one if the table has none. Reading through this accessor therefore has a side effect; use hasHead() or getHeaderRows() to inspect the table without adding a section to it.
      Returns:
      the table's <thead>.

    • hasHead

      public boolean hasHead()
      Reports whether this table already has a <thead>. Unlike getHead(), this does not create one.
      Returns:
      true if the table has a head.

    • setHead

      public void setHead(@Nullable TableHead head)
      Puts the given <thead> on this table, replacing the one it already has, if any.
      Parameters:
      head - the head to use, or null to remove the one the table has.

    • removeHead

      public void removeHead()
      Removes this table's <thead>, if it has one.

    • getFoot

      public TableFoot getFoot()
      Returns this table's <tfoot>, creating one if the table has none. Reading through this accessor therefore has a side effect; use hasFoot() or getFooterRows() to inspect the table without adding a section to it.
      Returns:
      the table's <tfoot>.

    • hasFoot

      public boolean hasFoot()
      Reports whether this table already has a <tfoot>. Unlike getFoot(), this does not create one.
      Returns:
      true if the table has a foot.

    • setFoot

      public void setFoot(@Nullable TableFoot foot)
      Puts the given <tfoot> on this table, replacing the one it already has, if any.
      Parameters:
      foot - the foot to use, or null to remove the one the table has.

    • removeFoot

      public void removeFoot()
      Removes this table's <tfoot>, if it has one.

    • getBodies

      public List<TableBody> getBodies()
      Returns the <tbody> elements of this table, in document order. A table may have several.
      Returns:
      the table's bodies.

    • getBody

      public TableBody getBody()
      Returns the first <tbody> of this table, creating one if the table has none. Reading through this accessor therefore has a side effect; use getBodies() or getBodyRows() to inspect the table without adding a body to it.
      Returns:
      the table's first body.

    • addBody

      public TableBody addBody()
      Appends a new <tbody> to this table, after any bodies it already has and before the <tfoot>.
      Returns:
      the new body.

    • addBody

      public TableBody addBody(TableBody body)
      Appends the given <tbody> to this table, after any bodies it already has and before the <tfoot>.
      Parameters:
      body - the body to add.
      Returns:
      the given body, for chaining.

    • removeBody

      public void removeBody(TableBody body)
      Removes the given <tbody> from this table.
      Parameters:
      body - the body to remove.

    • getAllRows

      public List<TableRow> getAllRows()
      Returns every row of this table, walking its sections in document order: the <thead> rows, then the rows of each <tbody>, then the <tfoot> rows.

      The name says All because this is the only row accessor that crosses section kinds. getHeaderRows(), getBodyRows() and getFooterRows() each stay within one kind, though getBodyRows does flatten several <tbody> elements when the table has them, and TableRowContainer.getRows(), TableRowContainer.getRows() and TableRowContainer.getRows() each return the rows of one container. addRow() appends to the body.

      Returns:
      all the rows of this table.

    • getHeaderRows

      public List<TableRow> getHeaderRows()
      Returns the rows of this table's <thead>, or an empty list if it has none. Unlike getHead(), this does not create the section, so it is safe to call while only reading the table ? from a debugger watch, for instance.
      Returns:
      the head's rows, in document order.

    • getBodyRows

      public List<TableRow> getBodyRows()
      Returns the rows of this table's <tbody> elements, in document order, or an empty list if it has none. Unlike getBody(), this does not create a body.
      Returns:
      the rows of every body, in document order.

    • getFooterRows

      public List<TableRow> getFooterRows()
      Returns the rows of this table's <tfoot>, or an empty list if it has none. Unlike getFoot(), this does not create the section.
      Returns:
      the foot's rows, in document order.

    • removeRow

      public void removeRow(TableRow row)
      Removes the given row from whichever section of this table holds it, so that a caller who added the row through addRow() or one of its siblings does not have to know which section that was.
      Parameters:
      row - the row to remove.
      Throws:
      IllegalArgumentException - if the row is not in any section of this table.

    • removeAllRows

      public void removeAllRows()
      Removes every row from this table, leaving its sections in place.

    • addRow

      public TableRow addRow()
      Appends a new empty row to this table's <tbody>, creating the body if the table has none. This mirrors what a browser does with a <tr> written straight inside a <table>. Use addHeaderRow() or addFooterRow() for the other sections; note that getAllRows() spans all three.

      A table may have several <tbody> elements. This one appends to the first, the same one getBody() returns; to append to another, call TableRowContainer.addRow() on the body you mean, which is what addBody() hands back.

      Returns:
      the new row.

    • addRow

      public TableRow addRow(String... cellTexts)
      Appends a row of data cells with the given texts to this table's <tbody>.

      For example, addRow("Mercury", "0.330") renders as: 

      
 <tbody>
   <tr>
     <td>Mercury</td>
     <td>0.330</td>
   </tr>
 </tbody>
      Parameters:
      cellTexts - the text content for each data cell.
      Returns:
      the new row.

    • addRow

      public TableRow addRow(List<String> cellTexts)
      List equivalent of addRow(String...).
      Parameters:
      cellTexts - the text content for each data cell.
      Returns:
      the new row.

    • addRowWithHeader

      public TableRow addRowWithHeader(String header, String... cellTexts)
      Appends a row led by a header cell labelling it, followed by data cells with the given texts. The leading cell is a <th scope="row">, which is what lets assistive technology announce the right label for each data cell in the row.

      For example, addRowWithHeader("Venus", "4.87", "12,104") renders as: 

      
 <tbody>
   <tr>
     <th scope="row">Venus</th>
     <td>4.87</td>
     <td>12,104</td>
   </tr>
 </tbody>
      Parameters:
      header - the text of the leading header cell.
      cellTexts - the text content for each data cell after it.
      Returns:
      the new row.

    • addRowWithHeader

      public TableRow addRowWithHeader(String header, List<String> cellTexts)
      List equivalent of addRowWithHeader(String, String...).
      Parameters:
      header - the text of the leading header cell.
      cellTexts - the text content for each data cell after it.
      Returns:
      the new row.

    • addRows

      public void addRows(TableRow... rows)
      Appends the given rows to this table's first <tbody>, creating the body if the table has none. As with addRow(), a table with several bodies gets the rows in the first of them.
      Parameters:
      rows - the rows to add.

    • addRows

      public void addRows(List<? extends TableRow> rows)
      List equivalent of addRows(TableRow...).
      Parameters:
      rows - the rows to add.

    • addHeaderRow

      public TableRow addHeaderRow()
      Appends a new empty row to this table's <thead>, creating it if the table has none.
      Returns:
      the new row.

    • addHeaderRow

      public TableRow addHeaderRow(String... cellTexts)
      Appends a row of header cells with the given texts to this table's <thead>.

      For example, addHeaderRow("Name", "Mass") renders as: 

      
 <thead>
   <tr>
     <th scope="col">Name</th>
     <th scope="col">Mass</th>
   </tr>
 </thead>
      Parameters:
      cellTexts - the text content for each header cell.
      Returns:
      the new row.

    • addHeaderRow

      public TableRow addHeaderRow(List<String> cellTexts)
      List equivalent of addHeaderRow(String...).
      Parameters:
      cellTexts - the text content for each header cell.
      Returns:
      the new row.

    • addHeaderRows

      public void addHeaderRows(TableRow... rows)
      Appends the given rows to this table's <thead>.
      Parameters:
      rows - the rows to add.

    • addHeaderRows

      public void addHeaderRows(List<? extends TableRow> rows)
      List equivalent of addHeaderRows(TableRow...).
      Parameters:
      rows - the rows to add.

    • addFooterRow

      public TableRow addFooterRow()
      Appends a new empty row to this table's <tfoot>, creating it if the table has none.
      Returns:
      the new row.

    • addFooterRow

      public TableRow addFooterRow(String... cellTexts)
      Appends a row of data cells with the given texts to this table's <tfoot>.

      For example, addFooterRow("Total", "1234") renders as: 

      
 <tfoot>
   <tr>
     <td>Total</td>
     <td>1234</td>
   </tr>
 </tfoot>
      Parameters:
      cellTexts - the text content for each data cell.
      Returns:
      the new row.

    • addFooterRow

      public TableRow addFooterRow(List<String> cellTexts)
      List equivalent of addFooterRow(String...).
      Parameters:
      cellTexts - the text content for each data cell.
      Returns:
      the new row.

    • addFooterRows

      public void addFooterRows(TableRow... rows)
      Appends the given rows to this table's <tfoot>.
      Parameters:
      rows - the rows to add.

    • addFooterRows

      public void addFooterRows(List<? extends TableRow> rows)
      List equivalent of addFooterRows(TableRow...).
      Parameters:
      rows - the rows to add.