Upgrade guide

volto-light-theme 8.0.0

Removed support for Volto 18.x.x

Added in version 8.0.0-alpha.0.

VLT 8.0.0 requires at least Volto 19.x.x.

@plone/components minimum version 4.0.0 alpha

Added in version 8.0.0-alpha.0.

VLT 8.0.0 requires @plone/components 4.0.0 alpha or above.

The recommended add-ons are not included by default as peerDependencies anymore

Added in version 8.0.0-alpha.0.

VLT 8.0.0 no longer includes the recommended add-ons as peerDependencies in package.json. You will need to install them manually if you want to use them in your project. The recommended add-ons are listed in the Recommended add-ons section.

Transferred all slider customizations to the @kitconcept/volto-slider-block add-on

Added in version 8.0.0-alpha.1.

All custom code related to the slider block has been moved to the @kitconcept/volto-slider-block add-on. If you have customized the slider block in your project, you will need to move your customizations shadows to the @kitconcept/volto-slider-block add-on as well.

Card link handling changed to CSS stretched-link pattern

Added in version 8.0.0-alpha.19.

The Card component no longer uses JavaScript click handlers to make the whole card interactive (role="link", tabIndex, onClick, onKeyDown). Instead, it uses a CSS stretched-link pattern: it creates a LinkToItem component (a ConditionalLink with the card-primary-link class) and passes it down through Card.Summary to its Summary children.

If you have a custom Summary component, you must update it to accept and use the LinkToItem prop to wrap the item title.

Old component signature:

const MySummary = ({ item, HeadingTag = 'div', a11yLabelId }) => (
  <>
    <HeadingTag className="title" id={a11yLabelId}>
      {item.title}
    </HeadingTag>
  </>
);

New component signature:

const MySummary = ({
  item,
  LinkToItem = React.Fragment,
  HeadingTag = 'div',
  a11yLabelId,
}) => (
  <>
    <HeadingTag className="title" id={a11yLabelId}>
      <LinkToItem>{item.title}</LinkToItem>
    </HeadingTag>
  </>
);

If you do not use LinkToItem, the title will still render correctly, but the stretched-link click target will be missing and the card will not be interactive.

Card title tag changed from heading to div

Added in version 8.0.0-alpha.19.

The default value of HeadingTag in all built-in Summary components has changed from h3 to div. Callers (listing templates, Teaser block) no longer pass HeadingTag="h2" or HeadingTag="h3" to Summary components.

If you have CSS selectors targeting heading tags inside cards or listing items (such as .card-summary h2, .listing-item h2.title, or .block.teaser .card-summary h2), you must update them to target the .title class instead:

/* Before */
.card-summary h2 { ... }
.listing-item h2.title { ... }

/* After */
.card-summary .title { ... }
.listing-item .title { ... }

Listing item markup changed from div to ul/li

Added in version 8.0.0-alpha.19.

All base listing templates (Default, Grid, Summary) now render the item list as a <ul> element with <li> children instead of nested <div> elements.

If you have CSS targeting div.items or div.listing-item, update those selectors to use the element-agnostic class selectors .items and .listing-item.

If you have customized a listing template by shadowing it, review your copy and update the wrapper elements accordingly:

<!-- Before -->
<div class="items">
  <div class="listing-item">...</div>
</div>

<!-- After -->
<ul class="items">
  <li class="listing-item">...</li>
</ul>

volto-light-theme 7.0.0

The card primitive has been applied to the Teaser block

Added in version 7.0.0-alpha.0.

The Teaser block now uses the new Card primitive. It is a new component that provides a consistent way to display content in a card format. It is used in the Teaser block, and it can be used in other blocks as well. The card component has the feature of allowing the user to select the text inside the card. From a developer's perspective, you can pass the elements (insets) inside the card as props.

If you have customized the Teaser block or any of its variants (left, right, top), you might need to adapt your customizations to use the new Card component. The inner structure of the Teaser block has changed, and the CSS classes have been updated to use the new Card component.

Old structure:

<div class="block teaser">
  <a>
    <div class="teaser-item default">
      <div class="image-wrapper">
        <img src="..." alt="..." />
      </div>
      <div class="content">
        <h2 class="title">...</h2>
        <p class="description">...</p>
      </div>
    </div>
  </a>
</div>

New structure:

<div class="block teaser">
  <div class="card">
    <a>
      <div class="card-inner">
        <div class="image-wrapper">
          <img src="..." alt="..." />
        </div>
        <div class="card-summary">
          <h2 class="title">...</h2>
          <p class="description">...</p>
        </div>
      </div>
    </a>
  </div>
</div>

• teaser-item default class has been replaced by the card-inner class.

• content class has been replaced by the card-summary class. The rest of the structure remains roughly the same.

The Teaser Body component has been shadowed

Added in version 7.0.0-alpha.4.

The shadow does not include the placeholder in case that the teaser is empty. This makes it easier to customize the Teaser block without having to override the entire component, including the placeholder. This is an excerpt of the new shadowed Teaser Body component:

<BlockWrapper
  {...props}
  className={cx(
    { [`${hasType?.toLowerCase()}-teaser`]: hasType },
    className,
  )}
>
  {isEmpty(data.href) && isEditMode ? (
    <div className="ui message">
      <div className="teaser-item placeholder">
        <img src={imageBlockSVG} alt="" />
        <p>{intl.formatMessage(messages.PleaseChooseContent)}</p>
      </div>
    </div>
  ) : (
    <BodyComponent {...props} />
  )}
</BlockWrapper>

If you have customized Teaser Body components, or registered components with Teaser depending on the content type, you will need to remove the placeholder from your them, as it is now handled by the Body component.

Changed h2 headline in captions to uses strong

For accessibility reasons we switched the <h2> in the image captions to <strong> as this better reflects the actual semantic role there. This should not effect you in most cases, but if you mirrored and customise the <Caption/> component you might want to amend this in your code as well.

volto-light-theme 6.0.0

This section describes how to upgrade to volto-light-theme 6.0.0 from 5.x.x. See each major version to upgrade between major versions.

New kitconcept.voltolighttheme backend package

VLT is now a package with both frontend and backend add-ons. Although it is not strictly mandatory, it is recommended for a better experience that you install the new backend package kitconcept.voltolighttheme in your backend build. Enable the site customization behaviors at least to your Plone site as shown in the Site customization documentation.

New look and feel and features for the footer

Added in version 6.0.0-alpha.22.

The footer has been overhauled to be more modular and extensible without shadowing. It has defined slots for the preFooter, postFooter, footer, footerLinks, and followUs areas.

It now also features the integration of @plonegovbr/volto-social-media so you can easily add social media links to your footer. See the section @plonegovbr/volto-social-media integration for more information.

If you have customized the footer in your site, you might need to adapt your customizations to use the new elements or remove the things that your design doesn't need.

@plonegovbr/volto-social-media integration

Added in version 6.0.0-alpha.22.

@plonegovbr/volto-social-media is a new feature that adds social media links and icons to your Plone site or subsite footer. It requires a new behavior plonegovbr.socialmedia.links to be installed in your Plone site or subsite. See the Social media section for more information.

All feature flags have been removed

Deprecated since version 6.0.0-alpha.20.

VLT used to have feature flags in the Volto configuration to enable or disable some theme features:

• config.settings.intranetHeader

• config.settings.enableFatMenu

• config.settings.siteLabel

These have been removed as feature flags, and moved to site customization settings. They are provided by the voltolighttheme.header behavior in the kitconcept.voltolighttheme add-on.

Plone portal actions in headers are no longer supported

Deprecated since version 6.0.0-alpha.20.

VLT no longer shows the Plone "portal actions" in the theme headers. They have been replaced by the add-on Actions feature. It is controlled by the headers_actions field, provided by the voltolighttheme.header behavior in the kitconcept.voltolighttheme add-on.

Updated data structure for footer_links and footer_logos.

Added in version 6.0.0-alpha.17.

The data structure used to hold the fields footer_links and footer_logos have changed. It used to have a blocks data structure (with blocks and blocks_data), but has been updated to use a bare array with the objects inside using the object_list widget. For the record, these are the shapes of the new objects:

type hrefType = {
  '@id': string;
  title: string;
} & Partial<Brain>;

type footerLink = {
  '@id': string;
  title: string;
  href: Array<hrefType>;
};

type footerLogo = {
  '@id': string;
  title: string;
  logo: Image;
  href: Array<hrefType>;
};

type footerLinks = Array<footerLink>
type footerLogos = Array<footerLogo>

Added in version 6.0.0-alpha.18.

An automatic upgrade step is provided with this version that updates the data structure in your Plone site root when the kitconcept.voltolighttheme behaviors are applied there.

If you've applied these behaviors to other content types, you'll need to create a custom upgrade step based on this one to update those content objects accordingly. The provided upgrade step serves as a helpful reference implementation.

Anontools component removed from headers

Deprecated since version 6.0.0-alpha.22.

The Anontools component was included alongside the site actions. If you want to restore it, you can add it as a header action by adding it to the headers_actions field, provided by the voltolighttheme.header behavior in the kitconcept.voltolighttheme add-on.

Color definitions

The VLT has migrated to use the standardized color definitions in Volto. These new definitions use CSS properties that are injected at runtime in the right places, so your CSS can adapt to use them in a generic way. The resultant CSS is simpler, and there's no need to define class names for each color definition. Read more about them in: https://6.docs.plone.org/volto/development/color-picker-widget.html?highlight=color#custom-css-properties-as-color-definitions

The new color definitions are no longer hardcoded, and now they are stored in config.blocks.themes for extensibility from your add-ons.

  config.blocks.themes = [
    {
      style: {
        '--theme-color': '#fff',
        '--theme-high-contrast-color': '#ecebeb',
        '--theme-foreground-color': '#000',
        '--theme-low-contrast-foreground-color': '#555555',
      },
      name: 'default',
      label: 'Default',
    },
    {
      style: {
        '--theme-color': '#ecebeb',
        '--theme-high-contrast-color': '#fff',
        '--theme-foreground-color': '#000',
        '--theme-low-contrast-foreground-color': '#555555',
      },
      name: 'grey',
      label: 'Grey',
    },
  ];

.block.teaser {
  background-color: var(---background-color, #fff)
}

Block widths

VLT has started to use the standard block width definition as well. It's stored in config.settings.blocksWidths. It uses a new widget component that would be ported to Volto core as soon as it's ready. This component saves the value of the custom CSS property --block-width as a StyleWrapper value, so it can be used later when the StyleWrapper injects it in the block (or component) markup.

Removed AlignWidget from src/components/Widgets

This component is removed because it was obsolete. Use the blockAlignment or blockWidth widgets instead.

volto-light-theme 5.0.0

The requirements for VLT have changed:

VLT version	Volto version
3.x.x	>= Volto 17.0.0-alpha.16
4.x.x	< Volto 17.18.0
5.x.x	>= Volto 17.18.0 or >=Volto 18.0.0-alpha.36

volto-light-theme 4.0.0

The tabbing order in the top header was fixed for accessibility concerns. It modifies the underlying HTML, moving from the top header to the bottom, and modifies the CSS to adjust.

The MobileNavigation component was updated to be more easily customizable. The component can now handle infinite navigation depth instead of only three levels, if configured to do so. The Burger Menu can now be easily customized by overriding the new MobileNavigationToggler.jsx file.

volto-light-theme 3.0.0

Blocks background colors go full width

The background colors previously snapped to 1440px. From 3.0.0-alpha.0 onward, this changed to be unconstrained by default, and expands to the end of the horizontal viewport.

Upgraded support for volto-slider-block 6.0.0

VLT upgraded the dependency on @kitconcept/volto-slider-block to use 6.0.0.

This is a drop-in replacement, so no action is required for the existing slider blocks you may already have in your sites. However, the CSS classes of the structural slider block elements changed in this version. The inner (visible objects) CSS classes remain unchanged. If you have customized them in your project, you may have to update them, although the structural class names are rarely customized aside from vertical spacing properties. They are mapped 1:1 with the previous ones, following this table correspondence:

Old className	New className
slick-slider	slider-wrapper
slick-list	slider-viewport
slick-track	slider-container
slick-slide	slider-slide
slick-arrow	slider-button
slick-prev	slider-button-prev
slick-next	slider-slide-next
slick-next	slider-slide-next
slick-dots	slider-dots
slick-dot	slider-dot

For more information, check the kitconcept/volto-slider-block and #288.

Language switcher shows the two-letter language code

The default in Volto is to show the full name of the language in the language switcher. VLT now shows only the two-letter language code.