> Markdown version of [Add Images and Icons](https://vaadin.com/docs/next/building-apps/ui-basics/add-images-icons). Section index: [llms.txt](https://vaadin.com/docs/next/building-apps/llms.txt)

# Add Images and Icons

This article shows how to display images using the `Image` component and how to use icons from built-in collections or custom SVG files. For the full API details, see the [Loading Resources](https://vaadin.com/docs/next/flow/advanced/loading-resources.md) and [Icons](https://vaadin.com/docs/next/components/icons.md) reference documentation.

## <a id="copy-paste-into-your-project"></a>Copy-Paste into Your Project

A self-contained view that displays an image and a button with an icon:

```java
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.html.Image;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

@Route("images-icons-example")
public class ImagesAndIconsExampleView extends VerticalLayout {

    public ImagesAndIconsExampleView() {
        Image logo = new Image("images/logo.png", "Company logo");
        Button call = new Button("Call", VaadinIcon.PHONE.create());
        add(logo, call);
    }
}
```

Place the image file at `src/main/resources/META-INF/resources/images/logo.png` (Spring Boot).

## <a id="images"></a>Images

The `Image` component wraps the HTML `<img>` element. You create one by providing a source and alt text.

### <a id="static-images"></a>Static Images

The most common approach is to place image files in your project’s static resource directory and reference them by path.

**Spring Boot (JAR)**: `src/main/resources/META-INF/resources/images/photo.png`

**Non-Spring (WAR)**: `src/main/webapp/images/photo.png`

In both cases, the code is the same:

```java
Image photo = new Image("images/photo.png", "A photo");
```

The servlet container or Spring MVC serves these files directly, giving you proper caching and range request support out of the box.

> **Tip:** Avoid a leading `/` in paths. Use relative paths like `"images/photo.png"`, not `"/images/photo.png"`.

### <a id="classpath-images"></a>Classpath Images

If your images are packaged inside a JAR (for example, in a reusable library or add-on) and not in the static resource directory, serve them through `DownloadHandler.forClassResource()`:

```java
Image image = new Image(
    DownloadHandler.forClassResource(getClass(), "/images/myimage.png"),
    "My image");
```

If the path starts with `/`, it resolves from the classpath root (`src/main/resources`). Without a leading `/`, it resolves relative to the class’s package.

> **Note:** Prefer static resources over `DownloadHandler` when possible. Static resources benefit from the servlet container’s built-in caching and range request handling. Use `DownloadHandler.forClassResource()` when the image is not in a static resource directory.

See [Downloads](https://vaadin.com/docs/next/flow/advanced/downloads.md) for more on `DownloadHandler`.

### <a id="images-from-byte-arrays"></a>Images from Byte Arrays

To show an image stored as a byte array — for example, a profile picture loaded from a database — pass the array and a file name to the `Image` constructor. The component serves the data to the browser through a [`DownloadHandler`](https://vaadin.com/docs/next/flow/advanced/downloads.md), and uses the extension of the file name to determine the MIME type. The file name is also used as the alternative text, so set a descriptive one with `setAlt()`:

```java
byte[] picture = personService.getProfilePicture(personId);
Image image = new Image(picture, "profile.png");
image.setAlt("Profile picture");
```

If the file name has no recognizable extension, or the MIME type is stored separately, pass it explicitly:

```java
Image image = new Image(picture, "profile", "image/jpeg");
```

### <a id="external-urls"></a>External URLs

The `Image` component also accepts full URLs:

```java
Image avatar = new Image("https://example.com/avatar.jpg", "User avatar");
```

### <a id="security-consideration"></a>Security Consideration

When your application uses [Spring Security](https://vaadin.com/docs/next/building-apps/security.md), static resources are protected by default. You need to explicitly permit access to image paths in your security configuration. See the security documentation for details.

## <a id="icons"></a>Icons

Vaadin provides built-in icon collections and supports custom SVG icons. Many Vaadin components accept icons natively — in buttons, menu items, text field prefixes, and more.

### <a id="built-in-icon-collections"></a>Built-in Icon Collections

Vaadin includes two icon collections out of the box.

**Vaadin Icons** — over 600 general-purpose icons:

```java
Icon icon = VaadinIcon.PHONE.create();
```

**Lumo Icons** — a curated set used by the default Lumo theme:

```java
Icon icon = LumoIcon.PHOTO.create();
```

The `VaadinIcon` and `LumoIcon` enums list all available icons. See the [Default Icons](https://vaadin.com/docs/next/components/icons/default-icons.md) page for the full set.

### <a id="icons-in-components"></a>Icons in Components

Many Vaadin components have built-in support for icons. A few common examples:

**Button with icon:**

```java
Button edit = new Button("Edit", VaadinIcon.EDIT.create());
```

**Icon-only button** (needs an accessible label):

```java
Button close = new Button(VaadinIcon.CLOSE.create());
close.setAriaLabel("Close");
```

**Text field with a prefix icon:**

```java
TextField address = new TextField("Address");
address.setPrefixComponent(VaadinIcon.MAP_MARKER.create());
```

> **Tip:** When a button shows only an icon and no text, always set an accessible label with `setAriaLabel()` so screen readers can announce it.

### <a id="custom-svg-icons"></a>Custom SVG Icons

For third-party or custom icons, use `SvgIcon` with the path to an SVG file in your static resources:

```java
SvgIcon icon = new SvgIcon("icons/custom-icon.svg");
```

For SVG sprite sheets containing multiple icons, append the symbol ID:

```java
SvgIcon icon = new SvgIcon("icons/sprites.svg#settings");
```

For icon fonts, icon styling (color, size), creating custom icon collection enums, and accessibility details, see the [Icons](https://vaadin.com/docs/next/components/icons.md) component documentation.