Recommendations

<allegro-recommendations> is a web component that fetches ranked article recommendations for the current reader via allegro.recommendations and renders them as a "Read Next" or "More Like This" list, reporting clicks automatically. The common case needs no JavaScript from the publisher — just place the tag.

See every state of <allegro-recommendations> in Storybook.

When no recommendations are available — no engine configured for the tenant, the engine unreachable, or the SDK call fails — the component renders nothing at all rather than an empty container.

Usage

<allegro-recommendations></allegro-recommendations>

With custom attributes:

<allegro-recommendations
    limit="4"
    heading="Read Next"
    layout="grid"
></allegro-recommendations>

Attributes

Attribute	Type	Default	Description
limit	text	(none)	How many articles to request. Defaults to 6 upstream; 24 is the maximum.
max-age-days	text	(none)	Excludes articles published more than this many days ago. Defaults to no cap.
path	text	(none)	Article to anchor the recommendations on. Defaults to the current page path.
heading	text	(none)	Heading shown above the list. When omitted, no heading is rendered.
layout	text	list	Layout for the rendered items: list or grid.
show-placeholder	boolean	true	Whether to reserve space with placeholder rows while loading. Set to false to render nothing until the items arrive.
tracking-data	text	(none)	Accepted like on every component, but has no effect here because the component records no events through allegro.track().

Loading Placeholder

While the request is in flight the component renders a grid of gray placeholder rows matching the requested limit and layout, and carries aria-busy="true" until the request settles. This reserves the space the items will occupy so the surrounding page does not shift when they arrive.

<allegro-recommendations show-placeholder="false"></allegro-recommendations>

Set show-placeholder="false" for placements where an empty gap is preferable to a visible skeleton — a sidebar that should collapse when the engine returns nothing, for instance. The component then stays empty until the items render.

Click Attribution

Each rendered item's link click calls allegro.recommendations.trackClick(item) with the exact item object the component rendered from, so attribution is resolved by identity rather than by path matching.

Shadow Parts

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS ::part() selector.

allegro-recommendations::part(item-title) {
    text-transform: uppercase;
}

Part	Description
wrapper	Wrapper around the heading and item list.
heading	The heading element, when heading is set.
items	The <ul> of rendered items.
item	Each <li> item wrapper.
item-link	Each item's <a> element.
item-image	Each item's <img> element, when the item has one.
item-title	Each item's title text.

Events

The component dispatches and listens to no events.

Tracked Events

The component records no events through allegro.track(). Item clicks are reported to the recommendations engine instead; see Click Attribution.

CSS Variables

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

allegro-recommendations {
    --recommendations--grid--columns: 4;
    --recommendations--item-title--font-weight: 700;
}

Defaults written below as u(n) mean n times --recommendations--base-font-size, the component's sizing unit. The unit defaults to the page's rem. If the host page sets a root font-size other than the usual 16px, pin it so the component sizes the same either way:

allegro-recommendations {
    --recommendations--base-font-size: 16px;
}

Layout & Typography

Variable	Default	Description
--recommendations--base-font-size	var(--allegro--font-size, 1rem)	Base sizing unit for the component.
--recommendations--color	var(--allegro--color-text, black)	Text color for the component.
--recommendations--font-family	var(--allegro--font-family, system-ui, sans-serif)	Font family for the component.
--recommendations--items--gap	u(1)	Gap between rendered items.
--recommendations--grid--columns	3	Number of columns in grid layout.
--recommendations--grid--columns-mobile	1	Number of columns in grid layout below 40em.

Heading

Variable	Default	Description
--recommendations--heading--color	var(--allegro--color-text, #111)	Heading text color.
--recommendations--heading--font-size	u(1.125)	Heading font size.
--recommendations--heading--font-weight	700	Heading font weight.

Items

Variable	Default	Description
--recommendations--item-image--aspect-ratio	16 / 9	Aspect ratio of each item image in grid layout, so every image is cropped to a uniform height regardless of its source dimensions.
--recommendations--item-image--background	#eee	Background behind item images and the loading placeholder rows.
--recommendations--item-image--border-radius	var(--allegro--radius, u(0.375))	Border radius of item images and the loading placeholder rows.
--recommendations--item-image--height	auto	Item image height in grid layout.
--recommendations--item-image--list-size	u(4.5)	Item image width and height in list layout.
--recommendations--item-title--color	var(--allegro--color-text, #111)	Item title text color.
--recommendations--item-title--font-size	u(0.9375)	Item title font size.
--recommendations--item-title--font-weight	600	Item title font weight.

Example: Dark Background

allegro-recommendations {
    --recommendations--color: #f5f5f5;
    --recommendations--heading--color: #fff;
    --recommendations--item-title--color: #fff;
    --recommendations--item-image--background: #333;
}

Related

• Recommendations guide — How ranking works, the allegro.recommendations API, and click attribution details.