vaadin-framework/documentation/components/components-link.asciidoc

---
title: Link
order: 8
layout: page
---

[[components.link]]
= Link

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

The [classname]#Link# component allows making hyperlinks. References to
locations are represented as resource objects, explained in
<<dummy/../../../framework/application/application-resources#application.resources,"Images
and Other Resources">>. The [classname]#Link# is a regular HTML hyperlink, that
is, an [literal]#++<a href>++# anchor element that is handled natively by the
browser. Unlike when clicking a [classname]#Button#, clicking a
[classname]#Link# does not cause an event on the server-side.

Links to an arbitrary URL can be made by using an [classname]#ExternalResource#
as follows:


[source, java]
----
// Textual link
Link link = new Link("Click Me!",
        new ExternalResource("http://vaadin.com/"));
----

You can use [methodname]#setIcon()# to make image links as follows:


[source, java]
----
// Image link
Link iconic = new Link(null,
        new ExternalResource("http://vaadin.com/"));
iconic.setIcon(new ThemeResource("img/nicubunu_Chain.png"));

// Image + caption
Link combo = new Link("To appease both literal and visual",
        new ExternalResource("http://vaadin.com/"));
combo.setIcon(new ThemeResource("img/nicubunu_Chain.png"));
----

The resulting links are shown in <<figure.components.link.basic>>. You could add
a " [literal]#++display: block++#" style for the icon element to place the
caption below it.

[[figure.components.link.basic]]
.[classname]#Link# Example
image::img/link.png[width=30%, scaledwidth=70%]

[[components.link.new-window]]
== Opening a New Window

With the simple constructor used in the above example, the resource is opened in
the current window. Using the constructor that takes the target window as a
parameter, or by setting the target window with [methodname]#setTargetName()#,
you can open the resource in another window, such as a popup browser window/tab.
As the target name is an HTML [literal]#++target++# string managed by the
browser, the target can be any window, including windows not managed by the
application itself. You can use the special underscored target names, such as
[literal]#++_blank++# to open the link to a new browser window or tab.

[source, java]
----
// Hyperlink to a given URL
Link link = new Link("Take me a away to a faraway land",
        new ExternalResource("http://vaadin.com/"));

// Open the URL in a new window/tab
link.setTargetName("_blank");

// Indicate visually that it opens in a new window/tab
link.setIcon(new ThemeResource("icons/external-link.png"));
link.addStyleName("icon-after-caption");
----

[[components.link.pop-up]]
== Opening as a Pop-Up Window

With the [literal]#++_blank++# target, a normal new browser window is opened. If
you wish to open it in a popup window (or tab), you need to give a size for the
window with [methodname]#setTargetWidth()# and [methodname]#setTargetHeight()#.
You can control the window border style with [methodname]#setTargetBorder()#,
which takes any of the defined border styles [parameter]#BorderStyle.DEFAULT#,
[parameter]#BorderStyle.MINIMAL#, and [parameter]#BorderStyle.NONE#. The
exact result depends on the browser.

[source, java]
----
// Open the URL in a popup
link.setTargetName("_blank");
link.setTargetBorder(BorderStyle.NONE);
link.setTargetHeight(300);
link.setTargetWidth(400);
----

== Alternatives

In addition to the [classname]#Link# component, Vaadin allows alternative ways to make hyperlinks.
Also, you can make hyperlinks (or any other HTML) in a [classname]#Label# in HTML content mode.

The [classname]#Button# component has a [parameter]#ValoTheme.BUTTON_LINK# style name that makes it look like a hyperlink, while handling clicks in a server-side click listener instead of in the browser.
However, browsers do not generally allow opening new windows after server side round trip, so for such tasks you need to use the [classname]#BrowserWindowOpener# extension described in <<dummy/../../../framework/advanced/advanced-windows#advanced.windows.popup, "Opening Pop-up Windows">>


== CSS Style Rules

[source, css]
----
.v-link { }
  a { }
    .v-icon {}
    span {}
----

The overall style for the [classname]#Link# component is [literal]#++v-link++#.
The root element contains the [literal]#++<a href>++# hyperlink anchor. Inside
the anchor are the icon, with [literal]#++v-icon++# style, and the caption in a
text span.

Hyperlink anchors have a number of __pseudo-classes__ that are active at
different times. An unvisited link has [literal]#++a:link++# class and a visited
link [literal]#++a:visited++#. When the mouse pointer hovers over the link, it
will have [literal]#++a:hover++#, and when the mouse button is being pressed over the link, the
[literal]#++a:active++# class. When combining the pseudo-classes in a selector,
please notice that [literal]#++a:hover++# must come after an
[literal]#++a:link++# and [literal]#++a:visited++#, and [literal]#++a:active++#
after the [literal]#++a:hover++#.

=== Icon Position

Normally, the link icon is before the caption.
You can have it right of the caption by reversing the text direction in the containing element.

[source, css]
----
/* Position icon right of the link caption. */
.icon-after-caption {
    direction: rtl;
}

/* Add some padding around the icon. */
.icon-after-caption .v-icon {
    padding: 0 3px;
}
----

The resulting link is shown in <<figure.components.link.new-window>>.

[[figure.components.link.new-window]]
.Link That Opens a New Window
image::img/link-new.png[width=25%, scaledwidth=50%]