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.

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	number	(empty)	How many articles to request. Defaults to 6 upstream; 24 is the maximum.
max-age-days	number	(empty)	Excludes articles published more than this many days ago. Defaults to no cap.
path	text	(empty)	Article to anchor the recommendations on. Defaults to the current page path.
heading	text	(empty)	Heading shown above the list. When omitted, no heading is rendered.
layout	select	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	(empty)	JSON object of custom data merged into every tracked event, e.g. "{'campaign': 'sidebar'}".

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.

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;
}

Variable	Default	Description
--recommendations--font-family	system-ui, sans-serif	Font family for the component.
--recommendations--heading--color	#111	Heading text color.
--recommendations--heading--font-size	1.125rem	Heading font size.
--recommendations--heading--font-weight	700	Heading font weight.
--recommendations--items--gap	1rem	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.
--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--border-radius	0.375rem	Item image border radius.
--recommendations--item-image--list-size	4.5rem	Item image size in list layout.
--recommendations--item-title--color	#111	Item title text color.
--recommendations--item-title--font-size	0.9375rem	Item title font size.
--recommendations--item-title--font-weight	600	Item title font weight.

Related

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