Docs

Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Link

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

Links to an arbitrary URL can be made by using an ExternalResource as follows:

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

You can use setIcon() to make image links as follows:

// 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 Link Example. You could add a " display: block" style for the icon element to place the caption below it.

link
Link Example

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 setTargetName(), you can open the resource in another window, such as a popup browser window/tab. As the target name is an HTML 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 _blank to open the link to a new browser window or tab.

// 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");

Opening as a Pop-Up Window

With the _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 setTargetWidth() and setTargetHeight(). You can control the window border style with setTargetBorder(), which takes any of the defined border styles BorderStyle.DEFAULT, BorderStyle.MINIMAL, and BorderStyle.NONE. The exact result depends on the browser.

// Open the URL in a popup
link.setTargetName("_blank");
link.setTargetBorder(BorderStyle.NONE);
link.setTargetHeight(300);
link.setTargetWidth(400);

Alternatives

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

The Button component has a 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 BrowserWindowOpener extension described in "Opening Pop-up Windows"

CSS Style Rules

.v-link { }
  a { }
    .v-icon {}
    span {}

The overall style for the Link component is v-link. The root element contains the <a href> hyperlink anchor. Inside the anchor are the icon, with 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 a:link class and a visited link a:visited. When the mouse pointer hovers over the link, it will have a:hover, and when the mouse button is being pressed over the link, the a:active class. When combining the pseudo-classes in a selector, please notice that a:hover must come after an a:link and a:visited, and a:active after the 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.

/* 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 Link That Opens a New Window.

link new
Link That Opens a New Window