Image

Image is a JDance component for displaying photographs, illustrations, logos and other visual content. Like other JDance components, images can be sized, styled and connected to server-side actions directly from Java.

For the complete API reference, visit https://doc.jdance.org.

Overview

The simplest way to display an image is to provide its URL. This can be a relative path within your application or an external image URL.

CODE

Image image = new Image("/img/jdanceGuiImages/imageTest_100.jpg");
image.setRelativeWidth(100);
image.setTooltip("Example image");

RESULT

The example uses a relative width of 100%, allowing the image to fill the space available in its parent layout.

Images in a layout

Images work with BasicLayout just like Text, Button and other JDance components.

The following example displays two images next to each other, with each image occupying half of the available layout width.

CODE

Image first = new Image("/img/jdanceGuiImages/imageTest_101.jpg");
first.setRelativeWidth(100);

Image second = new Image("/img/jdanceGuiImages/imageTest_102.jpg");
second.setRelativeWidth(100);

BasicLayout layout = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
layout.setRelativeWidth(100);
layout.setGap(12);
layout.add(first).setRelativeWidth(50);
layout.add(second).setRelativeWidth(50);

RESULT

Notice that the image width and the layout cell width are independent. The layout decides how much space each image receives, while setRelativeWidth(100) makes the image fill that space.

Images with other components

An Image can be combined with text, buttons and other elements to create cards, galleries and more complete interfaces.

Here we place an image and a caption inside a vertical layout.

CODE

Image image = new Image("/img/jdanceGuiImages/imageTest_103.jpg");
image.setRelativeWidth(100);
image.setTooltip("Image with caption");

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(10);
layout.add(image).setRelativeWidth(100);
layout.add(new Text("An image with a descriptive caption."));

RESULT

An image with a descriptive caption.

Fixed and relative dimensions

Image supports both fixed dimensions in pixels and relative dimensions in percentages.

Use fixed dimensions when an image should have a predictable size, such as an icon or thumbnail. Relative dimensions are useful for responsive content.

Image image = new Image("/img/jdanceGuiImages/imageTest_100.jpg");

// Fixed width in pixels
image.setWidth(240);

// Relative width instead
image.setRelativeWidth(100);

Choose one width strategy for each image. Setting both a fixed and relative width is unnecessary and can produce conflicting CSS declarations.

You can also specify a fixed height using setHeight() or a relative height using setRelativeHeight().

Responsive images

Image supports Media rules for fixed width and height, making it possible to change an image's dimensions depending on the screen size.

For example, a thumbnail can be larger on desktop and smaller on mobile.

Image image = new Image("/img/jdanceGuiImages/imageTest_101.jpg");
image.setWidth(300);
image.setWidth(new Media(0,700),160);

For fluid layouts, another common approach is to let BasicLayout handle responsive cell sizing and use setRelativeWidth(100) on the image itself.

Styling images

Images can have padding, borders and background colors using the same JDance styling concepts found elsewhere in the framework.

Image image = new Image("/img/jdanceGuiImages/imageTest_102.jpg");
image.setWidth(240);
image.setPadding(8);
image.setBackground(new Color("#F7F8FA"));
image.setBorder(new Border().setWidth(1).setRadius(8).setColor(new Color("#D8DEE8")));

Padding creates space around the image content. A border can help separate an image from the surrounding interface.

For properties not covered by the component API, addExplicitStyle() can be used, although JDance's dedicated styling methods should generally be preferred.

Interactive images

An image does not have to be purely decorative. Image supports events such as onClick, onMouseOver and onMouseOut.

Like other JDance components, images can trigger server-side actions.

Image image = new Image("/img/jdanceGuiImages/imageTest_103.jpg");
image.setWidth(240);
image.onClick(new ViewProductDetails());

Here, ViewProductDetails represents an application-specific HttpAction. This is an illustrative example; your application must provide that action.

You can also use Location for navigation or JavaScript for custom browser behavior.

Tooltips

Use setTooltip() to provide a short description that appears when the user hovers over an image.

Image image = new Image("/img/jdanceGuiImages/imageTest_100.jpg");
image.setTooltip("View the landscape");

The tooltip is rendered as the HTML title attribute. It is not a replacement for accessible alternative text, which may require an additional attribute.

Practical guidance

Use relative widths when images should adapt to their containers. Let BasicLayout handle the arrangement of multiple images, and use Media rules when different screen sizes require different dimensions.

Avoid forcing both width and height unless you intentionally want a specific aspect ratio. Otherwise, let the browser preserve the image's original proportions.

Choose image sizes appropriate for their display area. A small thumbnail should not require downloading a very large image file.

For meaningful images, provide accessible alternative text. With the current Image API, this can be added through addExplicitAttribute("alt",...).

Full API reference

These examples cover the most common ways to work with Image in JDance. The full API reference includes constructors, dimension methods, styling, event handlers and inherited functionality.

Visit https://doc.jdance.org for the full reference.