shopware/frontends - helpers

Welcome to @shopware/helpers package.

For getting started documentation visit https://frontends.shopware.com/

Documentation specific for this package: helpers

Reusable classes

The helpersCssClasses variable, defined in the cms/layoutClasses.ts helper file, comprises an array of class names utilized within the CMS.

To enhance type support, a union type HelpersCssClasses is defined, which encompasses all class names present in the helpersCssClasses array.

const visibilityMap: Record<CmsVisibility, HelpersCssClasses> = {
  mobile: "max-md:hidden",
  tablet: "md:max-lg:hidden",
  desktop: "lg:hidden",
};

These classes can be integrated into a custom template, thereby ensuring consistency across different packages. For example as a safelist classes in unocss configuration file

import { helpersCssClasses } from "@shopware/helpers";

export default defineConfig({
  safelist: helpersCssClasses,
});

getBackgroundImageUrl helper

The getBackgroundImageUrl function generates optimized CSS url() values for CMS background images. It extracts the raw URL, calculates the appropriate dimensions based on the media metadata, and applies image transformation parameters.

Usage

import { getBackgroundImageUrl } from "@shopware/helpers";

const optimizedUrl = getBackgroundImageUrl(
  "url(https://cdn.shopware.store/.../image.jpg)",
  cmsBlockOrSection, // object with backgroundMedia.metaData.width/height
  { format: "webp", quality: 85 }, // optional
);
// => 'url("https://cdn.shopware.store/.../image.jpg?width=1000&fit=crop,smart&format=webp&quality=85")'

Parameters

Parameter	Type	Description
url	string	CSS url() string containing the background image URL
element	{ backgroundMedia?: { metaData?: { width?: number; height?: number } } }	CMS section or block object with media metadata
options	BackgroundImageOptions (optional)	Format and quality settings

BackgroundImageOptions

type BackgroundImageOptions = {
  format?: string; // "webp" | "avif" | "jpg" | "png"
  quality?: number; // 0-100
};

When format or quality are provided, they are appended as query parameters to the image URL. If omitted, only the dimension and fit parameters are applied.

generateCdnSrcSet helper

Generates an HTML srcset string using CDN width-based resizing. Useful as a fallback when media has no pre-generated thumbnails — the CDN handles on-the-fly resizing via query parameters.

Usage

import { generateCdnSrcSet } from "@shopware/helpers";

const srcset = generateCdnSrcSet(
  "https://cdn.shopware.store/.../image.jpg",
  [400, 800, 1200, 1600], // optional, these are the defaults
  { format: "webp", quality: 85 }, // optional
);
// => "https://cdn.shopware.store/.../image.jpg?width=400&fit=crop,smart&format=webp&quality=85 400w, ...800w, ...1200w, ...1600w"

Parameters

Parameter	Type	Description
src	string | undefined	Base image URL
widths	number[] (optional)	Array of widths to generate (default: [400, 800, 1200, 1600])
options	{ format?: string; quality?: number } (optional)	Format and quality settings

Returns undefined if src is falsy or URL parsing fails.

buildCdnImageUrl helper

Builds an optimized CDN image URL with size parameters based on rendered element dimensions. Adds width or height (whichever is larger) rounded up to the nearest 100px, plus fit=crop,smart.

Usage

import { buildCdnImageUrl } from "@shopware/helpers";

const url = buildCdnImageUrl(
  "https://cdn.shopware.store/.../image.jpg",
  { width: 724, height: 760 },
);
// => "https://cdn.shopware.store/.../image.jpg?height=800&fit=crop,smart"

Parameters

Parameter	Type	Description
src	string | undefined	Base image URL
dimensions	{ width: number; height: number }	Rendered element dimensions in pixels

Returns an empty string if src is falsy. Returns the original src if URL parsing fails.

Changelog

Full changelog for stable version is available here

Latest changes: 1.6.0

Minor Changes

• #1985 2cbda25 Thanks @mkucmus! - Added methods to extract product info:

  • isProductOnSale
  • isProductTopSeller
  • getProductManufacturerName

• #2176 c647baf Thanks @mkucmus! - - Add getProductListingFromCmsPage helper to extract product listing from CMS page structure

  • Enable early access to listing data during SSR before component tree renders

Patch Changes

• #2030 22ff62e Thanks @mkucmus! - Extended ListingFilter type to support property options and manufacturer entities:

  • Added optional options property for property group options
  • Added optional entities property for manufacturer entities
  • Improved type safety by explicitly typing empty array return in getListingFilters()

• #2153 56cd178 Thanks @mkucmus! - Fix getSrcSetForMedia to properly encode special characters (spaces, commas, parentheses) in media URLs

• #2162 e1fae3e Thanks @mkucmus! - Export encodeUrlPath helper function to properly handle special characters (spaces, commas) in image URLs

API

getTranslatedProperty

Get translated property from the given object.

export function getTranslatedProperty<T>(
  element: T | undefined | null | never,
  property: keyof T,
): string

source code

downloadFile

Download file

export function downloadFile<T>(file: T, name: string)

source code

getBiggestThumbnailUrl

Returns the biggest thumbnail url from the media object

export function getBiggestThumbnailUrl<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

getMedia

Prepare media object

export function getMedia<
  T extends {
    downloads?: Array<{
      id: string;
      accessGranted: boolean;
      media: {
        fileName: string;
        fileExtension: string;
      };
    }>;
  },
>(lineItem: T)

source code

getSmallestThumbnailUrl

Returns the smallest thumbnail url from the media object

export function getSmallestThumbnailUrl<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

relativeUrlSlash

Add/remove slash from the relative path

export function relativeUrlSlash(relativeUrl: string, slash = true)

source code

urlIsAbsolute

export function urlIsAbsolute(url: string)

source code

canUseQuoteActions

export function canUseQuoteActions<
  T extends {
    stateMachineState?: {
      technicalName: string;
    };
  },
>(quote: T)

source code

encodeUrlPath

Encodes URL pathname to handle special characters (spaces, commas, etc.)

export function encodeUrlPath(urlString: string): string

source code

generateCdnSrcSet

Generates a srcset string using CDN width-based resizing. Useful as a fallback when media has no pre-generated thumbnails.

export function generateCdnSrcSet(
  src: string | undefined,
  widths: number[] = [400, 800, 1200, 1600],
  options?: { format?: string; quality?: number },
): string | undefined

source code

buildCdnImageUrl

Builds an optimized CDN image URL with size parameters. Adds width or height (whichever is larger) rounded up to the nearest 100px.

export function buildCdnImageUrl(
  src: string | undefined,
  dimensions: { width: number; height: number },
  options?: { format?: string; quality?: number },
): string

source code

getSrcSetForMedia

Returns the srcset attribute for the image, for available breakpoints

export function getSrcSetForMedia<
  T extends {
    thumbnails?: Array<{
      width: number;
      url: string;
    }>;
  },
>(media?: T): string | undefined

source code

getCmsLayoutConfiguration

Get layout configuration for CMS content

export function getCmsLayoutConfiguration<
  T extends CmsBlock | CmsSection | CmsSlot,
>(content: T): LayoutConfiguration

source code

expand LayoutConfiguration

export type LayoutConfiguration = {
  layoutStyles: {
    backgroundColor?: string | null;
    backgroundImage?: string | null;
    backgroundSize?: string | null;
    sizingMode?: string | null;
    marginBottom?: string | null | undefined;
    marginLeft?: string | null | undefined;
    marginRight?: string | null | undefined;
    marginTop?: string | null | undefined;
  };
  cssClasses: {
    [cssClass: string]: boolean;
  } | null;
};

LayoutConfiguration

export type LayoutConfiguration = {
  layoutStyles: {
    backgroundColor?: string | null;
    backgroundImage?: string | null;
    backgroundSize?: string | null;
    sizingMode?: string | null;
    marginBottom?: string | null | undefined;
    marginLeft?: string | null | undefined;
    marginRight?: string | null | undefined;
    marginTop?: string | null | undefined;
  };
  cssClasses: {
    [cssClass: string]: boolean;
  } | null;
};

source code

getProductListingFromCmsPage

Extracts the product listing data from a CMS page structure. Useful for SSR to get listing data early before components render.

export function getProductListingFromCmsPage<T = unknown>(
  cmsPage: CmsPageStructure,
): T | null

source code

getCmsEntityObject

Returns the main page object depending of the type of the CMS page.

export function getCmsEntityObject(
  response: CmsPageResponse,
): Product | Category | LandingPage

source code

isProduct

Predicate function to check if the entity is a product.

export function isProduct<T extends { apiAlias: string }>(
  entity: T | Product,
): entity is Product

source code

isCategory

export function isCategory<T extends { apiAlias: string }>(
  entity: T | Category,
): entity is Category

source code

isLandingPage

export function isLandingPage<T extends { apiAlias: string }>(
  entity: T | LandingPage,
): entity is LandingPage

source code

getProductFreeShipping

Get product free shipping property

export function getProductFreeShipping<
  T extends {
    shippingFree: boolean;
  },
>(product?: T): boolean

source code

getMainImageUrl

gets the cover image

export function getMainImageUrl<
  T extends
    | {
        cover: {
          media?: {
            url: string;
          };
        };
      }
    | {
        media?: Array<{
          media?: {
            url?: string;
          };
        }>;
      }
    | {
        cover: {
          url: string;
        };
      }
    | {
        cover: null;
      },
>(object: T): string

source code

getProductReviews

Format product reviews to ui-interfaces

export function getProductReviews<
  T extends {
    id: string;
    productReviews?: Array<{
      id: string;
      externalUser?: string;
      customerId?: string;
      createdAt: string;
      content: string;
      points?: number;
    }>;
  },
>({ product }: { product?: T } = {}): UiProductReview[]

source code

getProductName

export function getProductName<
  T extends {
    name: string;
  },
>({ product }: { product?: T } = {}): string | null

source code

getProductUrl

Get product url. The priority is SEO url and then technical url.

export function getProductUrl<
  T extends {
    id: string;
    seoUrls?: Array<{
      seoPathInfo?: string;
    }>;
  },
>(product?: T): string

source code

getProductTierPrices

Get the prices depending on quantity added to cart. Tier prices can be set in Advanced pricing tab in Product view (admin panel)

export function getProductTierPrices<
  T extends {
    calculatedPrices?: Array<{
      unitPrice: number;
      quantity: number;
    }>;
  },
>(product?: T): TierPrice[]

source code

getProductRatingAverage

Get product rating average property

export function getProductRatingAverage<T extends { ratingAverage: number }>(
  product: T,
): number | null

source code

getProductCalculatedListingPrice

Get the calculated list price

export function getProductCalculatedListingPrice<
  T extends {
    calculatedPrice?: CalculatedPrice;
    calculatedPrices?: CalculatedPrice[];
  },
>(product?: T): number | undefined

source code

getProductManufacturerName

Gets the translated name of the product manufacturer

export function getProductManufacturerName(
  product: ProductWithManufacturer,
): string

source code

getProductFromPrice

export function getProductFromPrice<
  T extends {
    calculatedPrice?: CalculatedPrice;
    calculatedPrices?: CalculatedPrice[];
  },
>(product: T): number | undefined

source code

getProductRoute

Get product route information for Vue router.

Returns product URL and route informations for resolving SEO url. Use it with combination of <RouterLink> or <NuxtLink> in Vue.js or Nuxt.js projects.

export function getProductRoute<
  T extends {
    id: string;
    seoUrls?: Array<{
      seoPathInfo?: string;
    }>;
  },
>(product?: T)

source code

isProductOnSale

Checks if a product is on sale based on its price percentage

export function isProductOnSale(product: {
  calculatedPrice: {
    listPrice?: {
      percentage?: number;
    } | null;
  };
}): boolean

source code

isProductTopSeller

Checks if a product is marked as a top seller

export function isProductTopSeller(product: {
  markAsTopseller?: boolean;
}): boolean

source code

getCategoryUrl

Get URL for category. Some link

export function getCategoryUrl<
  T extends {
    type: string;
    externalLink?: string;
    seoUrls?: { seoPathInfo: string }[];
    internalLink?: string;
    id: string;
    linkType?: string;
  },
>(category: T): string

source code

getCategoryBreadcrumbs

Gather breadcrumbs from category

export function getCategoryBreadcrumbs<
  T extends {
    translated?: {
      breadcrumb?: string[];
    };
    breadcrumb?: string[];
  },
>(
  category: T,
  options?: {
    /**
     * Start at specific index if your navigation
     * contains root names which should not be visible.
     */
    startIndex?: number;
  },
)

source code

getCategoryImageUrl

gets the cover image

export function getCategoryImageUrl<
  T extends {
    media?: { url: string };
    type: string;
  },
>(category: T): string

source code

getCategoryRoute

Get category/navigation route information for Vue Router.

Returns category or navigation URL and route informations for resolving SEO url. Use it with combination of <RouterLink> or <NuxtLink> in Vue.js or Nuxt.js projects.

Example:

<RouterLink :to="getCategoryRoute(navigationElement)">

export function getCategoryRoute<
  T extends {
    type: string;
    externalLink?: string;
    seoUrls?: { seoPathInfo: string }[];
    internalLink?: string;
    id: string;
    linkType?: string;
  },
>(category: T)

source code

getBackgroundImageUrl

export function getBackgroundImageUrl<
  T extends {
    backgroundMedia?: {
      metaData?: {
        width?: number;
        height?: number;
      };
    };
  },
>(url: string, element: T, options?: BackgroundImageOptions): string

source code

buildUrlPrefix

export function buildUrlPrefix(
  url: string | UrlRoute,
  prefix: string,
): UrlRouteOutput

source code

expand UrlRouteOutput

export type UrlRouteOutput = Omit<UrlRoute, "path"> & { path: string };

isMaintenanceMode

export function isMaintenanceMode<
  T extends {
    code?: string;
  },
>(errors: [T]): boolean

source code

getCmsBreadcrumbs

Build the breadcrumbs for the CMS page

export function getCmsBreadcrumbs<
  T extends {
    translated: {
      name: string;
    };
  },
>(page: T): { name: string }[]

source code

getCmsTranslate

Replace text placeholder with param value

export function getCmsTranslate(
  key: string,
  params?: { [key: string]: string | number | null | undefined } | null,
)

source code

getShippingMethodIcon

Get shipping method icon

export function getShippingMethodIcon<
  T extends {
    media?: {
      url: string;
    };
  },
>(shippingMethod: T)

source code

getPaymentMethodIcon

Get payment method icon

export function getPaymentMethodIcon<
  T extends {
    media?: {
      url: string;
    };
  },
>(paymentMethod: T)

source code

getFormattedPrice

Get formatted price

export function getFormattedPrice(
  value: string | number,
  currency: string,
  options: Options = {
    direction: "ltr",
    removeDecimals: false,
    removeCurrency: false,
  },
): string

source code

getLanguageName

Get translated language name

export function getLanguageName<
  T extends {
    translationCode?: { translated: { name: string } };
  },
>(language: T): string

source code

getShippingMethodDeliveryTime

Get shipping delivery time

export function getShippingMethodDeliveryTime<
  T extends {
    deliveryTime?: {
      translated: {
        name: string;
      };
    };
  },
>(shippingMethod: T)

source code

getListingFilters

biome-ignore lint/suspicious/noExplicitAny: Listing filters needs to be improved when schema types are ready

export function getListingFilters<T extends Record<string, any>>(
  aggregations: T | undefined | null,
): ListingFilter[]

source code