|
| 1 | +--- |
| 2 | +title: HTML Elements |
| 3 | +page-title: HTML Elements | Vaadin components |
| 4 | +description: Standard HTML elements that have direct counterparts in Vaadin Flow. |
| 5 | +meta-description: Standard HTML elements that have direct counterparts in Vaadin Flow. |
| 6 | +section-nav: badge-flow |
| 7 | +--- |
| 8 | + |
| 9 | + |
| 10 | += Components for Standard HTML Elements |
| 11 | + |
| 12 | +// tag::description[] |
| 13 | +Vaadin Flow comes with a set of components for standard HTML elements. |
| 14 | +// end::description[] |
| 15 | +Standard HTML components have an API that allows you to set most typical properties and attributes. You can also use the Element API to set any property or attribute, if the component API doesn't have an appropriate method. |
| 16 | + |
| 17 | +Components that can contain other components thereby implement the [interfacename]`HtmlContainer` interface to create a hierarchical structure. The Element API allows you to create any standard HTML element using the [classname]`Element` constructor. The [classname]`ElementFactory` class contains factory methods for many standard HTML elements. |
| 18 | + |
| 19 | +The module `flow-html-components` contains the following components: |
| 20 | + |
| 21 | +[cols="4,2,7",options=header] |
| 22 | +|=== |
| 23 | +| Component | HTML Element | Comments |
| 24 | +| `Anchor` | `a` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a[anchor element] defines a hyperlink to a resource. |
| 25 | +It can link to many kinds of targets, such as web pages, files, email addresses, or specific locations in the same page. |
| 26 | +| `Article` | `article` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/article[article element] is independent, self-contained content, such as a forum post, a blog entry, or a comment. For creating hyperlinks that navigate to a different route in your application, see <<{articles}/flow/routing/navigation#using-the-routerlink-component,RouterLink>> component. |
| 27 | +| `Aside` | `aside` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/aside[aside element] represents content that is indirectly related to the document’s main content, such as a sidebar. |
| 28 | +| `DescriptionList` | `dl` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl[description list element] represents a description list, commonly used to implement a glossary or to display metadata (a list of key-value pairs). |
| 29 | +| `Div` | `div` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/div[div element] is a generic container for content. |
| 30 | +| `Emphasis` | `em` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/em[emphasis element] is for words that have a stressed emphasis compared to surrounding text. |
| 31 | +| `FieldSet` | `fieldset` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/fieldset[field set element] is used to organize and group related inputs and their labels in a form. |
| 32 | +| `Footer` | `footer` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/footer[footer element] represents a footer for a document or a section, often containing content such as copyright notices, contact information, or links to related documents. |
| 33 | +| `H1`, .., `H6` | `h1`, .., `h6` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements[h1 to h6 elements] represent six levels of section headings, with `h1` being the highest level and `h6` the lowest, commonly used for page or section titles. |
| 34 | +| `Header` | `header` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/header[header element] represents a container for introductory content, usually containing a logo, a search form, and a heading element. |
| 35 | +| `Hr` | `hr` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/hr[horizontal rule element] represents a thematic break between paragraph-level content, typically rendered as a horizontal rule separating sections of text. |
| 36 | +| `Html` | any | Wrapper for raw HTML content. See the <<#html-component,HTML Component>> section for more information. |
| 37 | +| `HtmlObject` | `object` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/object[object element] defines a container for an external resource, such as a web page, a picture, a media player or a resource to be handled by a plugin. |
| 38 | +| `IFrame` | `iframe` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe[iframe element] represents a nested browsing context, used for embedding another HTML page into the current one. |
| 39 | +| `Image` | `img` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img[image element] is used to display an image within the web page. |
| 40 | +| `Input` | `input` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input[input element] defines a field where the user can enter data. For most use cases, there is a dedicated <<{articles}/components#,Vaadin component>> that provides more advanced functionality. |
| 41 | +| `ListItem` | `li` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/li[list item element] represents an item within a list. It is typically used inside an `OrderedList` or `UnorderedList`. |
| 42 | +| `Main` | `main` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/main[main element] represents the dominant content of a document’s `<body>`. Its content should be unique to the document and should not include material repeated across multiple pages, such as navigation links or footers. |
| 43 | +| `NativeButton` | `button` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button[button element] defines a clickable button. For most use cases, prefer the more advanced <<{articles}/components/button#,Vaadin Button>> component. |
| 44 | +| `NativeDetails` | `details` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details[details element] is often used to create an interactive widget that the user can open and close. For most use cases, prefer the more advanced <<{articles}/components/details#,Vaadin Details>> component. |
| 45 | +| `NativeLabel` | `label` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label[label element] represents a caption for a form control, typically an `input`. Since most <<{articles}/components#,Vaadin field components>> provide a `setLabel(String)` method, using a `NativeLabel` is generally unnecessary. |
| 46 | +| `NativeTable` | `table` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/table[table element] represents data presented in a two-dimensional table comprised of rows and columns of cells containing data. For most use cases, prefer the more advanced Vaadin <<{articles}/components/grid#,Grid>>, <<{articles}/components/grid-pro#,Grid Pro>> or <<{articles}/components/tree-grid#,Tree Grid>>. |
| 47 | +| `NativeTableBody` | `tbody` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tbody[table body element] encapsulates a set of table rows (`NativeTableRow`). |
| 48 | +| `NativeTableCaption` | `caption` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/caption[caption element] specifies the caption (or title) of a table, providing the table an accessible description. |
| 49 | +| `NativeTableCell` | `td` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/td[table data cell element] defines a cell of a table that contains data and may be used as a child of the `NativeTableRow`. |
| 50 | +| `NativeTableFooter` | `tfoot` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tfoot[table footer element] encapsulates a set of table rows (`NativeTableRow`), typically used to provide a summary for the columns. |
| 51 | +| `NativeTableHeader` | `thead` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/thead[table head element] encapsulates a set of table rows (`NativeTableRow`), indicating that they comprise the head of a table with information about the table's columns. |
| 52 | +| `NativeTableHeaderCell` | `th` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/th[table header element] defines a header cell, which can be used inside a `NativeTableRow`, typically within a `NativeTableHeader`. |
| 53 | +| `NativeTableRow` | `tr` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tr[table row element] defines a row of cells in a table. The row can contain either `NativeTableHeaderCell` or `NativeTableCell` elements. |
| 54 | +| `Nav` | `nav` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/nav[navigation element] defines a set of navigation links, typically used for menus, tables of contents, or indexes. Navigation is also supported by the more advanced <<{articles}/components/side-nav#,Vaadin Side Nav>> component. For menu implementations, see the <<{articles}/components/menu-bar#,Vaadin Menu Bar>> component. |
| 55 | +| `OrderedList` | `ol` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/ol[ordered list element] represents an ordered list of items (`ListItem`), typically rendered as a numbered list. |
| 56 | +| `Paragraph` | `p` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/p[paragraph element] represents a block of text, commonly known as a paragraph. |
| 57 | +| `Param` | `param` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/param[object parameter element] defines parameters for an <object> element. Usage is not recommended, as it has been deprecated in HTML. |
| 58 | +| `Pre` | `pre` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/pre[pre-formatted text element] represents pre-formatted text which is to be presented exactly as written in the HTML file, thus preserving both spaces and line breaks. |
| 59 | +| `RangeInput` | `input` | The range input element is an https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input[input element] with its `type` attribute set to `"range"`. It provides a dedicated API for slider-style inputs and is typically used to represent numeric values on a slider. |
| 60 | +| `Section` | `section` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/section[section element] represents a generic standalone section of a document. A section should typically include a heading (`H1`,...`H6`). |
| 61 | +| `Span` | `span` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/span[span element] is a generic inline container for phrasing content, which does not inherently represent anything. It is typically used to style a specific portion of text or as a placeholder for dynamic content. |
| 62 | +| `UnorderedList` | `ul` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/ul[unordered list element] represents an unordered list of items (`ListItem`), typically rendered as a bulleted list. |
| 63 | +|=== |
| 64 | + |
| 65 | + |
| 66 | +== HTML Component |
| 67 | + |
| 68 | +The `Html` class in Vaadin Flow allows developers to encapsulate and manage raw HTML fragments in server-side Java applications. This component is particularly useful when you have an HTML snippet -- either as a string or loaded from a file -- that you want to insert directly into your application's layout or routes. |
| 69 | + |
| 70 | +The `Html` class ensures that the HTML fragment is treated as a single unit with exactly one root element, which can be accessed and managed through the server-side code. |
| 71 | + |
| 72 | + |
| 73 | +=== Important Considerations |
| 74 | + |
| 75 | +Regarding the `Html` Component, there are a few things to consider. First, remember that developers are responsible for sanitizing the HTML content before passing it to the `Html` component. Failure to do so may lead to cross-site scripting (XSS) vulnerabilities, as the raw HTML is sent directly to the client. |
| 76 | + |
| 77 | +Once an `Html` object is created, the encapsulated HTML fragment cannot be modified. To change the content, a new `Html` instance must be created. |
| 78 | + |
| 79 | +You also need to know that the `Html` component doesn't expand the HTML into a server-side DOM tree. This means that while the root element can be accessed via `getElement()`, and the inner content via `getInnerHtml()`, you can't traverse or manipulate the DOM structure on the server side. |
| 80 | + |
| 81 | +Also, the HTML fragment must have exactly one root element. If the fragment contains multiple root elements, an `IllegalArgumentException` is thrown. |
| 82 | + |
| 83 | +Last thing to consider is that the `Html` component doesn't support SVG elements as a root node. For SVG content, the `Svg` component should be used instead. |
| 84 | + |
| 85 | +[discussion-id]`6774751B-921E-4B79-941E-830D9C3532B4` |
0 commit comments