Skip to main content
Logo
Explore APIsContact Us
  • Home
  • BET 3-in-1
  • Match Preview
  • Tournament Preview
  • Virtual Stadium
  • StatsHub
  1. Resources
  3. Engagement Tools
  5. Event List

Event List

Widgets, Engagement Tools, BET
Bet RecommendationHighlights
Last updated 3 days ago
Is this site helpful?
On this page
  • Key Capabilities
  • Placement Options
  • Settings and Customization
  • Styling Options
  • Requirements
  • Main Configurable Features
  • API Reference
  • Basic Properties
  • Theming
  • Custom Class Selectors
  • Integration
  • Widget Setup
  • onItemClick
  • Bet Slip Sync
  • Adapter Setup
  • Data Types
  • Tips

Event List widget (Listing widget) is a frontend visualization that displays a personalized event list sorted by the most relevant tournaments. The widget shows tournaments and events based on popularity and punters' betting history. It simplifies finding the right events among many options and boosts betting volume for both upcoming and live markets.

  • Punters past activity
  • General betting trends
  • Overall betting volume
  • Seasonal variations
  • New discovery and engagement patterns

Recommendation types

  • Recommended: Personalized list of recommendations based on punters betting history and preferences. Requires the user to be logged in.
  • Popular: List of the most popular items based on the total number of bets placed (no login required).
  • Trending: List of the currently trending items based on the number of recently placed bets (no login required).
info

Personalization requirement To enable personalized recommendations (the recommended type), you must provide a unique user identifier. When no user ID is provided, the widget will fall back to popular recommendations.

#Key Capabilities

Ranked Discovery

AI-sorted tournament list that prioritizes the most relevant competitions and events for each user.

Live & Pre-Match

Seamless support for highlighting high-relevance live games and upcoming pre-match opportunities.

Intelligent Sorting

Dynamic grouping of events by league and relevance, making it easy to navigate thousands of matches.

Volume Growth

Strategically surfaces top tournaments to drive higher betting engagement across popular markets.

Universal Adaptability

Responsive design that automatically scales from expansive desktop grids to focused mobile lists.

Full Integration

Direct access to client IDs and API endpoints ensures a flawless connection with your existing platform.

#Placement Options

Landing Hub

Ideal as the primary engagement area on your sportsbook homepage or landing center.

Sport Selection

Place on category pages to show the most relevant tournaments within a specific sport.

#Settings and Customization

  • Recommendation type: recommended, popular, or trending
  • Time span: live, upcoming, or both (default)
  • Sport filter: single sport or multiple sports
  • Sorting: relevancy or kickoff time

#Styling Options

  • Elements: colors
  • Text: font styles and colors
  • Sports selector: enable/disable (all sports selected if disabled)
  • Events/tournaments: number displayed (default 5)

#Requirements

  • Access to the client API

  • Required endpoints: User ID, Odds, Event info, Tournament info

  • Requires an adapter to be registered via SIR('registerAdapter', '{ADAPTER_NAME}'). See the adapter overview: https://apidocs.sportradar.online/resources/widgets/docs/adapter/Overview

  • widget-name: betRecommendation.eventList

Environment Requirements

Supported Browsers

BrowserVersionMobile Support
Chrome60+✅ Chrome Mobile 60+
Firefox55+✅ Firefox Mobile 55+
Safari12+✅ iOS Safari 12+
Edge79+✅ Edge Mobile 79+
Internet ExplorerAll versions❌ Not Supported

Technical Requirements:

Supported Sports
  • American Football NFL only (including NCAA)
  • Aussie Rules
  • Badminton
  • Bandy
  • Baseball & MLB
  • Basketball & NBA (including NCAA)
  • Beach soccer
  • Beach Volleyball
  • Cricket
  • Curling
  • Cycling
  • Darts
  • Field Hockey
  • Floorball
  • Futsal
  • Golf
  • Handball
  • Ice Hockey & NHL
  • Pesapallo
  • Rugby (League & Union)
  • Snooker
  • Soccer
  • Squash
  • Table Tennis
  • Tennis
  • Volleyball
  • Waterpolo
  • Winter sports

#Main Configurable Features

See the Event List widget demo.

Desktop View

Events grouped by league/tournament with expandable sections showing multiple events per competition.

Environment Requirements

Supported Browsers

BrowserVersionMobile Support
Chrome60+✅ Chrome Mobile 60+
Firefox55+✅ Firefox Mobile 55+
Safari12+✅ iOS Safari 12+
Edge79+✅ Edge Mobile 79+
Internet ExplorerAll versions❌ Not Supported

Technical Requirements:

#API Reference

#Basic Properties

PropertyTypeDefaultDescription
userstring|number0User identifier for personalized recommendations. When provided with filters.recommendationType.available: "recommended", the AI generates personalized suggestions. When 0 or omitted, the widget shows general recommendations.
outcomeNamePositionstring"start"Position of outcome label relative to odds button. Options: "start", "end", "top", "bottom". Affects market outcome visual layout.
onItemClickfunctionundefinedCallback function triggered when user clicks events or outcomes. Receives target (interaction type) and (selection details). Target types: (navigation), (bet slip). Use for bet slip integration and analytics tracking.

Extended Properties
PropertyTypeDefaultDescription
filtersobjectRequiredConfiguration for recommendation type, sports, and time filtering. See below for detailed structure.
numberOfEventsnumber25Maximum number of events to display per tournament/league. Controls density of events shown in each expanded competition section. Range: 1-50 events. Higher values show more events per tournament but increase vertical scroll. Lower values focus on top events.
numberOfExpandedCompetitionsnumber|string3Number of tournaments/leagues to display in expanded state on initial load. Options: Affects initial vertical height and user browsing pattern.

#Theming

Theming customization allows to tailor the appearance of Bet Recommendation widgets to meet specific needs and preferences. In the context of the Bet Recommendation widget, customization refers to the ability to modify the default styling of the widget by applying custom CSS properties to the various HTML elements that make up the widget.

Widget comes with pre-existing styling but can be customized by applying custom CSS properties to its different HTML elements. The widget's custom class selectors and supported CSS properties are listed below.

All custom classes must be nested within the .sr-bb.sr-eventlist selector class. This ensures that the custom styles only apply to that widget and not to other elements on the page.

#Custom Class Selectors

CSS classSupported CSS properties
srct-br-footercolor
srct-br-loadingbackground-color, border-radius
srct-br-outcomebackground-color, color, border-radius
srct-br-outcome--selectedbackground-color, color, border-radius
srct-br-outcome--disabledbackground-color, color, border-radius
srct-br-outcome--unavailablebackground-color, border-radius
srct-br-outcome__name,

#Integration

warning

Mandatory Configuration The filters property is required for this widget to function correctly. It defines the recommendation logic and basic data constraints.

Bet Recommendation technical guide

#Widget Setup

#onItemClick

The onItemClick callback is fired whenever the user interacts with the widget. The first argument is a target string that identifies the interaction type; the second argument is a data object containing contextual information.

target valueTriggerKey data properties
"externalOutcome"User clicks a single outcome buttonexternalEvent, externalMarket, externalOutcome
"externalOutcomes"User clicks multiple outcomes at once (e.g. combo card)Array of { externalEvent, externalMarket, externalOutcome }
"externalEvent"User clicks an event header/cardexternalEvent
"externalCompetition"User clicks a competition/league name

Note: Widgets support callbacks on outcome clicks — the onItemClick handler receives target === "outcome" and a data object containing externalEvent, externalMarket and externalOutcome. Use this for custom outcome callbacks (e.g., add-to-betslip, analytics, modals).

The widget also exposes onTrack for event tracking analytics. See the tracking guide for details.

#Bet Slip Sync

To keep the widget's selected-outcome state in sync with your own bet slip (i.e. show outcomes as selected when they were added outside the widget), use registerOnBetSlipChange inside registerAdapter.

javascript
// 1. Track your bet slip state
let changeCallback;
let betSlipState = { betslip: [], combinedOddsValue: undefined };

// 2. Notify the widget whenever the bet slip changes
function onBetSlipChanged

#Adapter Setup

An adapter is a software component developed by the Sportradar engineering team that bridges the Bet Recommendation widgets and your platform's API. It retrieves data from your API and feeds it to the widget, ensuring seamless communication between the two systems.

Before adapter development begins, confirm and align your API contract with the Sportradar engineering team. Integration requires two SIR calls:

SIR methodPurpose
SIR('registerAdapter', ...)Configure the adapter that retrieves and displays data from your API.
SIR('addWidget', ...)Mount the widget on the page.
javascript
(function

#Data Types

The following data types are provided by the adapter and are also available in the onItemClick callback payload.

Event

PropertyTypeRequiredDescription
idstring | numberYesSportradar event ID.
externalIdstring | number—Client-side event ID.
datestringYesFormatted date string displayed in the widget.

#Tips

  • Enabling H2H data (headToHeadEnable: true) increases each card's height by approximately 50–90px. H2H data is not useful on live events.
  • The "recommended" type requires a user with sufficient betting history; without it, the widget may fall back to popular recommendations.
  • JavaScript enabled
  • XMLHttpRequest support for data fetching
  • CSS3 support for styling and animations
  • JavaScript enabled
  • XMLHttpRequest support for data fetching
  • CSS3 support for styling and animations
data
"event"
"outcome"
hideMarketNameRowbooleanfalseHides market name labels in event cards. When true, removes market name text rows (e.g., "Match Result"), showing only outcomes and odds. Reduces card height for compact layouts.
collapseLayoutbooleanfalseForces mobile/collapsed layout on small breakpoints. When true, applies vertical stacked layout optimized for narrow containers even on tablet/desktop widths. Useful for sidebar placements.
showMoreMarketsButtonbooleanfalseDisplays "More Markets" button on each event card. When true, shows button linking to full event page with complete market list. Enables discovery of additional betting options.
  • 1, 2, 3: Specific number of expanded tournaments (most relevant first). User can manually expand/collapse others.
  • "all": All tournaments expanded simultaneously. Shows complete view without interaction. Best for comprehensive overviews.
orderBystring"+begin"Sorting order for events within each tournament section. Options:
  • "+begin": Chronological order (earliest events first). Best for scheduled betting, pre-match focus, time-sensitive planning.
  • "relevance": AI-determined relevance order based on recommendation scores, popularity, user preferences. Best for discovery, high-value events first, personalized experiences.
sportsMappingobjectundefinedMaps client's sport identifiers to Sportradar sport IDs. Object with keys as client sport IDs (string/number) and values as Sportradar sport IDs. Example: {101: 1, 102: 2} maps client sport 101 to soccer, 102 to basketball. Allows using client's sport taxonomy in filter configurations.
similarEventIdsarray<number>undefinedArray of event IDs for "similar" recommendation type. Required when filters.recommendationType.available: "similar". AI finds events similar to specified reference events based on sport, league, teams, odds patterns, timing. Example: [12345, 67890] finds events similar to these matches. Useful for "Related Events" sections on match detail pages.
headToHeadEnablebooleanfalseEnables embedded head-to-head comparison widget within each event card. When true, displays H2H button/section showing team statistics, recent form, past meetings. Adds informational depth but increases card height. Best for pre-match betting where historical context valuable.
headToHeadLabelstring"H2H"Custom label text for head-to-head button. Only applies when headToHeadEnable: true. Localize this label for different languages (e.g., "Form", "Stats", "History").
headToHeadGamePulseBtnEnablebooleanfalseShows Game Pulse button within head-to-head section. Only applies when headToHeadEnable: true. Game Pulse provides live match momentum indicators and advanced statistics.
headToHeadGamePulseBtnTooltipbooleanfalseEnables tooltip for Game Pulse button explaining feature. Only applies when both headToHeadEnable: true and headToHeadGamePulseBtnEnable: true.
headToHeadShowGamePulsebooleanfalseAutomatically displays Game Pulse content without button click. Only applies when headToHeadEnable: true. Shows momentum data inline for immediate access.
enableCashbackIconbooleanfalseDisplays cashback indicator icon on eligible events. When true, shows icon/badge on events where operator offers cashback promotions. Requires backend configuration of cashback-eligible events. Enhances promotional visibility.
cashbackIconstringundefinedCustom URL/path for cashback icon image. Only applies when enableCashbackIcon: true. Use to match operator's cashback branding. Example: "/assets/cashback-badge.svg". Falls back to default icon if omitted.
streamIconstringundefinedCustom URL/path for live stream icon image. Displays on events with available live streaming. Use to match operator's streaming branding. Example: "/assets/stream-icon.svg". Falls back to default icon if omitted.
streamIconPositionstringundefinedPosition of stream icon within event card. Options: "start" (left side near teams), "end" (right side near odds). Affects visual hierarchy and space allocation.
debugbooleanfalseEnables debug mode with console logging for development. When true, logs recommendation generation, API calls, event filtering, league grouping, expand/collapse actions, errors with stack traces. Use for troubleshooting integration issues and understanding recommendation logic.

Filters Object

The filters object controls recommendation algorithms, time windows, and sport filtering.

PropertyTypeDefaultDescription
recommendationTypeobjectRequiredRecommendation algorithm configuration.
recommendationType.availablestring"recommended"Required. Recommendation type to use. Options:
  • "recommended": AI-powered personalized recommendations based on user betting history (requires user parameter). Analyzes user's favorite sports, preferred leagues/teams, typical odds ranges, bet timing patterns, market type preferences, win rates by competition.
  • "popular": Most popular events across all users. Shows events with highest betting volume, number of unique bettors, consistent popularity. Social proof effect, safe recommendations.
  • "trending": Events experiencing momentum and increasing popularity. Captures betting volume spikes, rapid odds changes, unusual activity patterns, social media buzz. Time-sensitive opportunities, ideal for live betting.
  • "similar": Events similar to specified reference events (requires similarEventIds parameter). AI finds comparable matches based on sport, league, teams, odds, timing.
Unlike Highlights widget, Event List shows single recommendation type (no tabs or multiple types).
sportobjectundefinedSport filter configuration.
sport.availablearray<string|number>[]Array of Sportradar sport IDs to include. Empty array or omitted shows all available sports. Example: [1, 2, 5] for soccer, basketball, tennis only. Filters both tournaments and events by specified sports. See Sports Reference.
sport.sportNamesbooleanfalseDisplay mode for sport indicators in tournament headers. When true, shows sport names as text labels. When false, shows sport-specific icons (⚽ soccer, 🏀 basketball, etc.). Set true for accessibility or when icons are unclear.
timeobjectundefinedTime/status filter configuration for event scheduling.
time.rangenumber0Time window in hours for upcoming events. Defines maximum hours ahead to include events. Range: 0-72 hours. Examples:
  • 0: No time limit (show all future events)
  • 3: Only events starting within next 3 hours
  • 12: Only events starting within next 12 hours (half-day window)
  • 24: Events starting today/tomorrow (1 day window)
  • 72: Events within next 3 days
Only applies to upcoming events (time.available: "not_started"). Ignored for live events. Useful for focusing on immediate betting opportunities or limiting long-term forecasts.
time.availablestringundefinedEvent status filter. Options:
  • "live": Only live/in-play events. Shows matches currently in progress. Best for live betting hubs.
  • "not_started": Only upcoming/pre-match events. Shows scheduled future matches. Best for pre-match betting, planning ahead.
  • Omitted: Shows both live and upcoming events (no status filtering).

Filters Example

javascript
{
  recommendationType: {
    available: 'popular'  // Single type (not array like Highlights)
  },
  sport: {
    available: [1, 2, 5],  // Soccer, Basketball, Tennis
    sportNames: false  // Show sport icons
  },
  time: {
    range: 12,  // Next 12 hours
    available: 'not_started'  // Upcoming events only
  }
}
font-size
color
srct-br-outcome__valuefont-size, color
srct-br-eventinfofont-size, color
srct-br-eventinfo__infofont-size
srct-br-eventinfo__iconcolor
srct-br-eventinfo__timefont-size, color
srct-br-eventinfo__statusfont-size, color
srct-br-eventinfo__namefont-size, color
srct-br-scoreboardfont-size, color
srct-br-scoreboard__teamsfont-size, color
srct-br-scoreboard__scoresfont-size, color
srct-br-scoreboard__score-1font-size, color
srct-br-scoreboard__score-2font-size, color
srct-br-scoreboard__score-3font-size, color
srct-br-market__namefont-size, color
srct-br-market__typefont-size, color
srct-br-market__more-marketsbackground-color, color, border-radius
srct-br-eventcardbackground, color
srct-br-leagueinfobackground, font-size, color, border
srct-br-leagueinfo__infofont-size, color
srct-br-leagueinfo__iconfont-size, color
srct-br-table__contentbackground-color
srct-br-table__headerfont-size, color, background-color
srct-br-table__subheaderfont-size, color, background-color
srct-br-table__cellborder
srct-br-table__row-spacingwidth

Basic tournament list with popular recommendations.

JavaScript

javascript
SIR("addWidget", "#event-list-1", "betRecommendation.eventList", {
  numberOfEvents: 25,
  numberOfExpandedCompetitions: 3,
  filters: {
    recommendationType: {
      available: "popular",
    },
  },
});

HTML (data attributes)

html
<div
  class="sr-widget"
  data-sr-widget="betRecommendation.eventList"
  data-number-of-events="25"
  data-number-of-expanded-competitions="3"
  data-filters='{"recommendationType": {"available": "popular"}}'
></div>
externalCompetition
"goToBetSlip"User clicks the "Go to Bet Slip" button (swipeBet only)—
"betSlipMode"Bet slip mode changes between single and multi (swipeBet only)value: "single" | "multi"
javascript
SIR("addWidget", "#sr-widget", "betRecommendation.markets", {
  onItemClick: function (target, data) {
    if (target === "externalOutcome") {
      // Add single outcome to bet slip
      const { externalEvent, externalMarket, externalOutcome } = data;
      betSlip.add({
        eventId: externalEvent.id,
        marketId: externalMarket.id,
        outcomeId: externalOutcome.id,
      });
    } else if (target === "externalEvent") {
      // Navigate to event/match detail page
      window.location.href = `/matches/${data.externalEvent.id}`;
    } else if (target === "externalCompetition") {
      // Navigate to competition/league page
      window.location.href = `/league/${data.externalCompetition.tournament.id}`;
    }
  },
  filters: { recommendationType: { available: "popular" } },
});
(
callback
)
{
changeCallback = callback;
changeCallback && changeCallback(betSlipState); // push current state immediately
}
// 3. Handle outcome clicks from the widget
function onItemClick(target, data) {
if (target === "externalOutcome") {
const newBet = {
externalEventId: data.externalEvent.id,
externalMarketId: data.externalMarket.id,
externalOutcomeId: data.externalOutcome.id,
externalSpecifierId: data.externalMarket.specifier
? data.externalMarket.specifier.value
: undefined,
};
betSlipState = {
betslip: [...betSlipState.betslip, newBet],
combinedOddsValue: "14.52", // replace with your own calculation
};
changeCallback && changeCallback(betSlipState);
}
}
// 4. Register adapter with bet slip sync + add the widget
SIR("registerAdapter", "{ADAPTER_NAME}", { onBetSlipChanged });
SIR("addWidget", "#sr-widget", "betRecommendation.markets", { onItemClick });

Until a custom adapter is developed, use the mockData adapter for local testing:

javascript
SIR("registerAdapter", "mockData", { onBetSlipChanged });
(
a
,
b
,
c
,
d
,
e
,
f
,
g
,
h
,
i
)
{
a[e] ||
((i = a[e] =
function () {
(a[e].q = a[e].q || []).push(arguments);
}),
(i.l = 1 * new Date()),
(i.o = f),
(g = b.createElement(c)),
(h = b.getElementsByTagName(c)[0]),
(g.async = 1),
(g.src = d),
g.setAttribute("n", e),
h.parentNode.insertBefore(g, h));
})(
window,
document,
"script",
"https://widgets.sir.sportradar.com/sportradar/widgetloader",
"SIR",
{ language: "en" },
);
SIR("registerAdapter", "{ADAPTER_NAME}");
SIR("addWidget", "#sr-widget", "betRecommendation.markets");
sport.idstring | numberYesSport ID. Use sportsMapping if not using Sportradar sport IDs.
sport.namestringYesSport name.
category.idstring | number—Category ID.
category.namestringYesCategory name (e.g. "England").
tournament.idstring | number—Tournament/league ID.
tournament.namestringYesTournament name.
teamsArray<{id, name}>YesHome and away competitors.
isLivebooleanYesWhether the event is currently live.
liveCurrentTimestringYesLive time display (e.g. "2nd set", "45'").
result1 / result2 / result3result—Score columns: { result: [homeScore, awayScore] }.

Market

PropertyTypeRequiredDescription
idstring | numberYesMarket ID.
namestring—Market name (e.g. "Match Winner").
status.isActiveboolean—When false, see Widget Behavior.

Outcome

PropertyTypeRequiredDescription
idstring | numberYesOutcome ID.
namestringYesOutcome name (e.g. "Home", "Draw").
oddsstring | numberYesOdds value. Use a number type to enable odds-change indicators (up/down arrows).
specifier.valuestring | number—Additional specifier (e.g. handicap value "-2.50").
status.isActiveboolean—When false, see Widget Behavior.