path: root/documentation/components/components-label.asciidoc

---
title: Label
order: 7
layout: page
---

[[components.label]]
= [classname]#Label#

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-presentation/label]
endif::web[]

[classname]#Label# component displays non-editable text. This text can be used
for short simple labels or for displaying long text, such as paragraphs. The
text can be formatted in HTML or as preformatted text, depending on the
__content mode__ of the label.

You can give the label text most conviniently in the constructor, as is done in
the following. Label has 100% default width, so the containing layout must also
have defined width.


[source, java]
----
// A container that is 100% wide by default
VerticalLayout layout = new VerticalLayout();

Label label = new Label("Labeling can be dangerous");
layout.addComponent(label);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].

[classname]#Label# implements the [interfacename]#Property# interface to allow
accessing the text value, so you can get and set the text with
[methodname]#getValue()# and [methodname]#setValue()#.


[source, java]
----
// Get the label's text to initialize a field
TextField editor = new TextField(null, // No caption
                                 label.getValue());
        
// Change the label's text
editor.addValueChangeListener(event -> // Java 8
    label.setValue(editor.getValue()));
editor.setImmediate(true); // Send on Enter
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].

Label also supports data binding to a property data source, as described later
in <<components.label.databinding>>. However, in that case the value can not be
set through the label, as [classname]#Label# is not a
[interfacename]#Property.Editor# and is not allowed to write to a bound
property.

Even though [classname]#Label# is text and is often used as a caption, it is a
normal component and therefore also has a caption that you can set with
[methodname]#setCaption()#. As with most other components, the caption is
managed by the containing layout.

[[components.label.wrap]]
== Text Width and Wrapping

[classname]#Label# has 100% default width, so the containing layout must also
have a defined width. If the width of the label's text exceeds the width of the
label, the text will wrap around and continue on the next line. Some layout
components have undefined width by default, such as
[classname]#HorizontalLayout#, so you need to pay special care with them.


[source, java]
----
// A container with a defined width.
Panel panel = new Panel("Panel Containing a Label");
panel.setWidth("300px");

panel.setContent(
    new Label("This is a Label inside a Panel. There is " +
              "enough text in the label to make the text " +
              "wrap when it exceeds the width of the panel."));
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.wrap[on-line example, window="_blank"].

As the size of the [classname]#Panel# in the above example is fixed and the
width of [classname]#Label# is the default 100%, the text in the
[classname]#Label# will wrap to fit the panel, as shown in
<<figure.components.label>>.

[[figure.components.label]]
.The Label Component
image::img/label-example1.png[]

Setting [classname]#Label# to undefined width will cause it to not wrap at the
end of the line, as the width of the content defines the width. If placed inside
a layout with defined width, the [classname]#Label# will overflow the layout
horizontally and, normally, be truncated.


[[components.label.content-mode]]
== Content Mode

The content of a label is formatted depending on a __content mode__. By default,
the text is assumed to be plain text and any contained XML-specific characters
will be quoted appropriately to allow rendering the contents of a label in HTML
in a web browser. The content mode can be set in the constructor or with
[methodname]#setContentMode()#, and can have the values defined in the
[classname]#ContentMode# enumeration type in
[package]#com.vaadin.shared.ui.label# package:

TEXT:: The default content mode where the label contains only plain text. All
characters are allowed, including the special [literal]#++<++#,
[literal]#++>++#, and [literal]#++&++# characters in XML or HTML, which are
quoted properly in HTML while rendering the component. This is the default mode.

PREFORMATTED:: Content mode where the label contains preformatted text. It will be, by default,
rendered with a fixed-width typewriter font. Preformatted text can contain line
breaks, written in Java with the [literal]#++\n++# escape sequence for a newline
character (ASCII 0x0a), or tabulator characters written with [literal]#++\t++#
(ASCII 0x09).

HTML:: Content mode where the label contains HTML.

+
Please note the following security and validity warnings regarding the HTML
content mode.




[WARNING]
.Cross-Site Scripting Warning
====
Having [classname]#Label# in HTML content mode allows pure HTML content. If the
content comes from user input, you should always carefully sanitize it to
prevent cross-site scripting (XSS) attacks. Please see
<<dummy/../../../framework/advanced/advanced-security#advanced.security.sanitizing,"Sanitizing
User Input to Prevent Cross-Site Scripting">>.

Also, the validity of the HTML content is not checked when rendering the
component and any errors can result in an error in the browser. If the content
comes from an uncertain source, you should always validate it before displaying
it in the component.

====



The following example demonstrates the use of [classname]#Label# in different
modes.


[source, java]
----
Label textLabel = new Label(
    "Text where formatting characters, such as \\n, " +
    "and HTML, such as <b>here</b>, are quoted.",
    ContentMode.TEXT);

Label preLabel = new Label(
    "Preformatted text is shown in an HTML <pre> tag.\n" +
    "Formatting such as\n" +
    "  * newlines\n" + 
    "  * whitespace\n" +
    "and such are preserved. HTML tags, \n"+
    "such as <b>bold</b>, are quoted.",
    ContentMode.PREFORMATTED);

Label htmlLabel = new Label(
    "In HTML mode, all HTML formatting tags, such as \n" +
    "<ul>"+
    "  <li><b>bold</b></li>"+
    "  <li>itemized lists</li>"+
    "  <li>etc.</li>"+
    "</ul> "+
    "are preserved.",
    ContentMode.HTML);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.content-modes.contentmodes[on-line example, window="_blank"].

The rendering will look as shown in <<figure.components.label.content-mode>>.

[[figure.components.label.content-mode]]
.Label Content Modes
image::img/label-modes.png[]


ifdef::web[]
[[components.label.spacing]]
== Spacing with a [classname]#Label#

You can use a [classname]#Label# to create vertical or horizontal space in a
layout. If you need a empty "line" in a vertical layout, having just a label
with empty text is not enough, as it will collapse to zero height. The same goes
for a label with only whitespace as the label text. You need to use a
non-breaking space character, either [literal]#++&nbsp;++# or
[literal]#++&#160;++#:


[source, java]
----
layout.addComponent(new Label("&nbsp;", ContentMode.HTML));
----

Using the [parameter]#ContentMode.PREFORMATTED# mode has the same effect;
preformatted spaces do not collapse in a vertical layout. In a
[classname]#HorizontalLayout#, the width of a space character may be
unpredictable if the label font is proportional, so you can use the preformatted
mode to add em-width wide spaces.

If you want a gap that has adjustable width or height, you can use an empty
label if you specify a height or width for it. For example, to create vertical
space in a [classname]#VerticalLayout#:


[source, java]
----
Label gap = new Label();
gap.setHeight("1em");
verticalLayout.addComponent(gap);
----

You can make a flexible expanding spacer by having a relatively sized empty
label with [literal]#++100%++# height or width and setting the label as
expanding in the layout.


[source, java]
----
// A wide component bar
HorizontalLayout horizontal = new HorizontalLayout();
horizontal.setWidth("100%");

// Have a component before the gap (a collapsing cell)
Button button1 = new Button("I'm on the left");
horizontal.addComponent(button1);

// An expanding gap spacer
Label expandingGap = new Label();
expandingGap.setWidth("100%");
horizontal.addComponent(expandingGap);
horizontal.setExpandRatio(expandingGap, 1.0f);

// A component after the gap (a collapsing cell)
Button button2 = new Button("I'm on the right");
horizontal.addComponent(button2);
----

endif::web[]

[[components.label.databinding]]
== Data Binding

While [classname]#Label# is not a field component, it is a
[interfacename]#Property.Viewer# and can be bound to a property data source,
described in
<<dummy/../../../framework/datamodel/datamodel-properties#datamodel.properties,"Properties">>.
You can specify the data source either in the constructor or by the
[methodname]#setPropertyDataSource()# method.


[source, java]
----
// Some property
ObjectProperty<String> property =
    new ObjectProperty<String>("some value");
        
// Label that is bound to the property
Label label = new Label(property);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.binding[on-line example, window="_blank"].

Further, as [classname]#Label# is a [interfacename]#Property#, you can edit its
value with a property editor, such as a field:


[source, java]
----
Label label = new Label("some value");
TextField editor = new TextField();
editor.setPropertyDataSource(label);
editor.setImmediate(true);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.delegation[on-line example, window="_blank"].

However, [classname]#Label# is __not__ a [interfacename]#Property.Editor#, so it
is read-only when bound to a data source. Therefore, you can not use
[methodname]#setValue()# to set the value of a connected data source through a
[classname]#Label# nor bind the label to an editor field, in which case writes
would be delegated through the label.


[[components.label.css]]
== CSS Style Rules


[source, css]
----
.v-label { }
  pre { } /* In PREFORMATTED content mode */
----

The [classname]#Label# component has a [literal]#++v-label++# overall style. In
the [parameter]#PREFORMATTED# content mode, the text is wrapped inside a
[literal]#++<pre>++# element.