Responsive Themes

Vaadin includes support for responsive design which enables size range conditions in CSS selectors, allowing conditional CSS rules that respond to size changes in the browser window on the client-side.

See the Vaadin Blog article on Responsive design for some additional information.

You can use the Responsive extension to extend either a component, typically a layout, or the entire UI. You specify the component by the static makeResponsive() method.

  1. // Have some component with an appropriate style name
  2. VerticalLayout l = new VerticalLayout();
  4. Label c = new Label("Here be text");
  5. l.addStyleName("myresponsive");
  6. l.addComponent(c);
  8. // Enable Responsive CSS selectors for the component
  9. Responsive.makeResponsive(l);

You can now use width-range and height-range conditions in CSS selectors as follows:

  1. /* Basic settings for all sizes */
  2. .myresponsive {
  3.     padding: 5px;
  4.     line-height: 36pt;
  5. }
  7. /* Small size */
  8. .myresponsive[width-range~="0-300px"] {
  9.     background: orange;
  10.     font-size: 16pt;
  11. }
  13. /* Medium size */
  14. .myresponsive[width-range~="301px-600px"] {
  15.     background: azure;
  16.     font-size: 24pt;
  17. }
  19. /* Anything bigger */
  20. .myresponsive[width-range~="601px-"] {
  21.     background: palegreen;
  22.     font-size: 36pt;
  23. }

You can have overlapping size ranges, in which case all the selectors matching the current size are enabled.

Note that responsive themes currently do not work together with stylesheets or widget sets loaded from a different domain than the Vaadin application. Such resources must be loaded from the same domain as the application. The problem occurs only in Firefox. A SecurityError is shown in the debug window. The limitation concerns stylesheets such as for web fonts served from external sites, as described in “Loading Web Fonts”.

Flexible Wrapping

You can use the CssLayout to have automatic wrap-around when the components in the layout would go off right side of the layout. Components that wrap must, however, have either undefined or fixed width, and thereby can not utilize the full area of the screen. With the Responsive extension, you can have more flexible wrap-around that gives the component tiles maximum width.

In the following, we have a text and image box, which are laid out horizontally with 50-50 sizing if the screen is wide enough, but wrap to a vertical layout if the screen is narrow.

  1. CssLayout layout = new CssLayout();
  2. layout.setWidth("100%");
  3. layout.addStyleName("flexwrap");
  4. content.addComponent(layout);
  6. // Enable Responsive CSS selectors for the layout
  7. Responsive.makeResponsive(layout);
  9. Label title = new Label("Space is big, really big");
  10. title.addStyleName("title");
  11. layout.addComponent(title);
  13. Label description = new Label("This is a " +
  14.     "long description of the image shown " +
  15.     "on the right or below, depending on the " +
  16.     "screen width. The text here could continue long.");
  17. description.addStyleName("itembox");
  18. description.setSizeUndefined();
  19. layout.addComponent(description);
  21. Image image = new Image(null,
  22.         new ThemeResource("img/planets/Earth.jpg"));
  23. image.addStyleName("itembox");
  24. layout.addComponent(image);

The SCSS could be as follows:

  1. /* Various general settings */
  2. .flexwrap {
  3.     background: black;
  4.     color: white;
  6.     .title {
  7.         font-weight: bold;
  8.         font-size: 20px;
  9.         line-height: 30px;
  10.         padding: 5px;
  11.     }
  13.     .itembox {
  14.         white-space: normal;
  15.         vertical-align: top;
  16.     }
  18.     .itembox.v-label {padding: 5px}
  19. }
  21. .flexwrap[width-range~="0-499px"] {
  22.     .itembox {width: 100%}
  23. }
  25. .flexwrap[width-range~="500px-"] {
  26.     .itembox {width: 50%}
  27. }

The layout in the wide mode is shown in Flexible Wrapping.

addon responsive flexwrap

Flexible Wrapping

You could also play with the display: block vs display: inline-block properties.

Notice that, while the Responsive extension makes it possible to do various CSS trickery with component sizes, the normal rules for component and layout sizes apply, as described in “Layout Size” and elsewhere, and you should always check the size behaviour of the components. In the above example, we set the label to have undefined width, which disables word wrap, so we had to re-enable it.

Toggling the Display Property

The display property allows especially powerful ways to offer radically different UIs for different screen sizes by enabling and disabling UI elements as needed. For example, you could disable some parts of the UI when the space gets too small, but bring forth navigation buttons that, when clicked, add component styles to switch to the hidden parts.

In the following, we simply show alternative components based on screen width:

  1. CssLayout layout = new CssLayout();
  2. layout.setWidth("100%");
  3. layout.addStyleName("toggledisplay");
  4. content.addComponent(layout);
  6. // Enable Responsive CSS selectors for the layout
  7. Responsive.makeResponsive(layout);
  9. Label enoughspace =
  10.     new Label("This space is big, mindbogglingly big");
  11. enoughspace.addStyleName("enoughspace");
  12. layout.addComponent(enoughspace);
  14. Label notenoughspace = new Label("Quite small space");
  15. notenoughspace.addStyleName("notenoughspace");
  16. layout.addComponent(notenoughspace);

The SCSS could be as follows:

  1. /* Common settings */
  2. .toggledisplay {
  3.     .enoughspace, .notenoughspace {
  4.         color: white;
  5.         padding: 5px;
  6.     }
  8.     .notenoughspace { /* Really small */
  9.         background: red;
  10.         font-weight: normal;
  11.         font-size: 10px;
  12.         line-height: 15px;
  13.     }
  15.     .enoughspace { /* Really big */
  16.         background: darkgreen;
  17.         font-weight: bold;
  18.         font-size: 20px;
  19.         line-height: 30px;
  20.     }
  21. }
  23. /* Quite little space */
  24. .toggledisplay[width-range~="0-499px"] {
  25.     .enoughspace    {display: none}
  26. }
  28. /* Plenty of space */
  29. .toggledisplay[width-range~="500px-"] {
  30.     .notenoughspace {display: none}
  31. }

Responsive Demos

You can find a simple responsive demo at demo.vaadin.com/responsive. It demonstrates the flexible wrapping technique described in Flexible Wrapping.

The Parking demo for TouchKit uses a responsive theme to adapt to mobile devices with different screen sizes and when the screen orientation changes.