Toplist3 (Toplist v3)

Migration Notice: This widget uses the legacy bw-widget tag. While still supported, consider using nw-blocks for new implementations.

Overview

The Toplist3 widget is a modern, card-based brand comparison widget that displays brands in a responsive grid layout. Unlike table-based Toplist variants, Toplist3 uses individual styled cards with social proof ribbons, bonus displays, star ratings, and customizable CTA buttons. It supports both old (selling-point-type) and new (sellingpointtype) naming conventions.

Key Features

  • Card-Based Layout: Individual brand cards with hover effects and shadows
  • Social Proof Ribbons: Top-rated, exclusive, and custom social proof indicators
  • Flexible Grid: Responsive 3-column desktop, 2-column tablet, 1-column mobile
  • Maximum 9 Brands: Optimized for category pages with maxrows up to 9
  • Custom CTA Colors: Full control over button colors and hover states
  • Bonus Display Control: Three-level control with hideBonuses, hideBonusRibbon, hideBonusText
  • Heading & Intro Support: Customizable H1-H6 headings with alignment control
  • Product Filtering: Support for CA, SB, BI, PO, LO, LI, FN, ES, CR, CF, ST
  • Bonus Type Filtering: Filter by tb, ndb, fs, and other bonus types
  • Eager Loading: Performance optimization via eagercount attribute
  • Hero Mode: Special rendering mode when used with Hero widget
  • Translation Support: i18n keys for all text elements
  • Compliance Disclaimers: Age restrictions and terms & conditions display

Usage Examples

Basic Toplist3 with New Naming Convention

Expand me...

Toplist3 with Old Naming Convention (Container Width ≤ 600px)

Expand me...

Toplist3 Standard Layout (Container Width > 600px)

Expand me...

Toplist3 with No Deposit Bonus Filter

Expand me...

Toplist3 for Sportsbook Product

Expand me...

Toplist3 with Custom CTA Colors

Expand me...

Attributes Reference

Attribute Type Default Description
id string Required Widget identifier - must be toplist3
product string undefined Product type filter: CA, SB, BI, PO, LO, LI, FN, ES, CR, CF, ST
referer string undefined Tracking referer parameter appended to tracking URLs
short string undefined Short identifier for brand selection
country string fr Country code (ISO 2-letter). Supports state codes: US-NJ, CA-ON
country-state string undefined State/province code for US/CA
selling-point-type / sellingpointtype string general Type of selling points to display (both naming conventions supported)
currency string EUR Currency code (converted to uppercase)
language string en Language code (ISO 2-letter)
max-rows / maxrows number 9999 Maximum number of brands to display (recommended max: 9)
cloaked-link / cloakedlink string cresus-casino Cloaked link identifier for tracking
tracking-data / trackingdata string "" Additional tracking data appended to URLs
tracking-target / trackinglinktarget string "" Tracking target path (e.g., homepage, games)
rating number 4.5 Minimum rating filter
cta-key / ctakey string cta-claim-bonus Translation key for CTA button text
cta-text / ctatext string "" Default CTA button text (fallback)
min-width / minwidth string undefined Minimum width for CTA button (e.g., 180px)
heading-text / headingtext string "" Custom heading text
heading-key / headingkey string "" Translation key for heading text
heading-level / headinglevel string h2 Heading level: h1, h2, h3, h4, h5, h6, p
heading-alignment / headingalignment string Center Heading alignment: Left, Center, Right
show-sub-heading / showsubheading boolean true Show/hide heading and intro text
introtext string "" Intro paragraph text below heading
intro-text-alignment / introtextalignment string Center Intro text alignment: Left, Center, Right
rel string nofollow Link rel attribute
target string _blank Link target attribute
bonus-type / bonustype string tb Bonus type filter: tb, ndb, fs, etc.
cta-colors / ctacolors string ["#05842A", "#05842A"] CTA button gradient colors (JSON array or single color)
cta-hover-colors / ctahovercolors string ["#096725", "#096725"] CTA button hover gradient colors
eager-count / eagercount number 0 Number of brands to load eagerly (for LCP optimization)

CTA Color Format Options

The ctacolors and ctahovercolors attributes support multiple formats:

  1. JSON Array (gradient): '["#05842A", "#05842A"]' or '["red", "yellow"]'
  2. Single Color: 'green' or '#05842A'
  3. Parsed by parseColors utility: Handles both string and array inputs

Widget Components

Toplist3 Container Component

Main wrapper that organizes all brand cards:

  • Heading Component: Uses Heading atom for H1-H6 generation with alignment
  • Main Title: Styled heading with configurable alignment
  • Sub Title: Intro text paragraph with alignment control
  • Content Area: Grid container for all Toplist3Row cards
  • Row Slicing: Only renders up to maxRows count (recommended max: 9)
  • Debug Info: Hidden CloudFlare rayID and dcKey paragraphs

Toplist3Row Component

Individual brand card with comprehensive information display:

Card Structure

  • Card Container: Styled box with shadow, border-radius, and hover effects
  • Hero Mode Support: Special rendering when isHero flag is true
  • Social Proof Ribbon: Positioned at top of card with icon + text
  • Logo Section: Brand logo with eager/lazy loading control
  • Brand Name: Clickable (if review page exists) or plain text
  • Star Rating: SVG sprite-based rating display
  • Bonus Section:
    • Bonus tag/ribbon (if not hidden)
    • Main bonus text
    • Additional bonus text (e.g., freespins)
    • Exclusive badge
  • CTA Button: Full-width button with custom gradient colors
  • Disclaimer Section: Age restriction + compliance text + T&C link

Social Proof Ribbons

Supported ribbon types with icons:

  • top-rated: DoubleStarsIcon + “Top-Rated” text
  • exclusive: DiamondIcon + “Exclusive” text
  • gift: GiftIcon + custom text
  • Custom ribbons via socialRibbonKey attribute

Bonus Display Logic

Three-level control for bonus visibility:

  1. hideBonuses: Hides entire bonus section
  2. hideBonusRibbon: Hides “Bonus” tag/ribbon only
  3. hideBonusText: Hides bonus amounts/text only
  4. isAllBonusDataHidden: When both ribbon and text are hidden
  5. noBonus: When no bonus text exists or all bonus data hidden

CTA Styling

  • Dynamic Colors: Uses useTolpistCta hook for computed styles
  • Gradient Support: Two-color gradients from ctaColors array
  • Hover Effects: Separate hover colors via ctaHoverColors
  • Min Width: Configurable minimum button width
  • Translation: i18n key support via ctaKey attribute

Hooks Used

  • useTopListData: Processes brand data (logo, name, URLs, etc.)
  • useStarRating: Generates star rating component
  • useTolpistCta: Computes CTA button styles from color arrays

Responsive Behavior

Desktop (≥1000px)

  • Grid Layout: 3 columns
  • Card Width: Equal width distribution
  • Gap: Standard spacing between cards
  • Hover Effects: Shadow and scale transforms

Tablet (600px - 999px)

  • Grid Layout: 2 columns
  • Card Width: 50% minus gap
  • Reduced Gap: Tighter spacing for tablet screens

Mobile (<600px)

  • Grid Layout: 1 column
  • Card Width: 100% (full width)
  • Stack Layout: Vertical stacking of all cards
  • Optimized Touch: Larger touch targets for mobile

Common Use Cases

Category Landing Pages

Display top 6-9 brands for specific categories (casinos, sportsbooks, poker rooms).

No Deposit Bonus Pages

Filter with bonustype="ndb" to show only no deposit offers.

Regional Gambling Portals

Use country and language attributes for geo-specific content.

Product-Specific Pages

Filter by product attribute to show relevant vertical (CA, SB, PO, BI).

Homepage Hero Sections

Display top 3 brands with maxrows="3" for featured placement.

Comparison Pages

Show side-by-side brand comparisons with social proof ribbons.

Mobile-Optimized Lists

Single-column card layout automatically adapts for mobile users.

Performance-Critical Pages

Use eagercount to load above-the-fold brands for better LCP.

Multi-Language Sites

Leverage translation keys for full localization support.

Affiliate Campaign Pages

Track campaigns with trackingdata and referer attributes.

Best Practices

Content Strategy

  • Optimal Brand Count: Display 6-9 brands for best engagement (max 9 recommended)
  • Product Filtering: Always specify product for relevant results
  • Bonus Type Specificity: Use bonustype for specialized pages
  • Social Proof: Enable social ribbons for trust signals

User Experience

  • Clear Headings: Use descriptive H1/H2 headings for context
  • Intro Text: Provide brief intro for page context
  • Review Links: Enable info icons linking to detailed reviews
  • CTA Clarity: Use action-oriented button text

Visual Design

  • Card Consistency: Maintain uniform card styling across site
  • Color Coordination: Match CTA colors to brand guidelines
  • Hover Effects: Subtle hover states improve interactivity
  • Social Ribbons: Use appropriate ribbon types for context

Performance Optimization

  • Eager Loading: Set eagercount="3" for above-fold cards
  • Lazy Loading: Let below-fold cards load lazily
  • Max Rows Limit: Keep under 9 brands per page
  • Image Optimization: Use optimized logo assets

Accessibility

  • Semantic HTML: Proper heading hierarchy with H1-H6
  • Link Context: Clear link purposes for screen readers
  • Color Contrast: Ensure CTA buttons meet WCAG standards
  • Keyboard Navigation: All interactive elements keyboard-accessible

SEO Considerations

  • H1 Usage: Use headinglevel="h1" for main page headings
  • Heading Alignment: Left for traditional, center for featured
  • NoFollow Links: Affiliate links use rel="nofollow"
  • Structured Layout: Card-based layout clear for search engines

Advanced Configuration

Custom CTA Color Gradients

Create brand-specific button styling:

ctacolors='["#FF6B00", "#CC5500"]'
ctahovercolors='["#CC5500", "#993300"]'

Multi-Product Filtering

Combine product and bonus type:

<nw-blocks id="toplist3" product="CA" bonustype="ndb" maxrows="6" \></nw-blocks>

Regional State Filtering

Filter for US/Canadian states:

<nw-blocks id="toplist3" country="US" language="en" \></nw-blocks>

Campaign Tracking

Add tracking parameters:

<nw-blocks id="toplist3" referer="homepage-cta" trackingdata="campaign=summer2025" \></nw-blocks>

Performance Tuning

Optimize Core Web Vitals:

<nw-blocks id="toplist3" eagercount="3" maxrows="9" \></nw-blocks>

Naming Convention Flexibility

Use either old or new attribute naming:

<!-- Old Convention -->
<nw-blocks id="toplist3" selling-point-type="general" max-rows="6" \></nw-blocks>

<!-- New Convention -->
<nw-blocks id="toplist3" sellingpointtype="general" maxrows="6" \></nw-blocks>

Data Requirements

Sanity CMS Structure

Each brand card requires:

  • brandId: Unique identifier
  • brandName: Display name
  • trackingLink: Cloaked tracking link
  • trackingData: Tracking parameters
  • trackingTarget: Target path (e.g., homepage)
  • imgUrl: Logo image URL
  • alt: Logo alt text
  • bonus: Main bonus text
  • bonusExtra: Additional bonus text
  • bonusTranslationKey: i18n key for bonus
  • extraFreespins: Freespins count
  • rating: Star rating (0-5)
  • socialRibbonKey: Social proof ribbon identifier
  • socialProofKey: Hero mode ribbon (if isHero=true)
  • reviewPageUrl: Object with url property
  • complianceDisclaimer: Object with disclaimer HTML
  • hasTrackingLink: Boolean for T&C link
  • isExclusive: Boolean for exclusive badge
  • hideBonuses: Boolean to hide all bonus data
  • hideBonusRibbon: Boolean to hide bonus ribbon
  • hideBonusText: Boolean to hide bonus text
  • minimumAge: Age restriction text
  • introTextValues: Array (not used in Toplist3 cards)

Brand KV Storage

Cached with keys: brand-{product}-{cloakedLink} (lowercase)

Translation Keys

  • CTA: cta-claim-bonus, cta-bet-now, cta-play-now, etc.
  • Heading: Custom via headingkey attribute
  • Intro: Via introtext attribute or i18n key
  • Bonus: Via bonusTranslationKey field
  • Social Ribbons: Via socialRibbonKey field
  • Terms: wgt-toplist-terms for T&C link

Error Handling

Missing Data

  • No Logo: Falls back to alt text or placeholder
  • No Review Page: Brand name displays as plain text
  • No Bonus: Entire bonus section hidden
  • No Social Ribbon: Card renders without ribbon
  • Missing Disclaimer: Terms section hidden
  • No Tracking Link: T&C link not rendered

Configuration Errors

  • Invalid Max Rows: Defaults to 9999 (shows all, but max 9 recommended)
  • Invalid CTA Colors: Falls back to default green (#05842A)
  • Invalid Product: Shows all products if product code invalid
  • Invalid Bonus Type: Shows all bonus types if bonustype invalid

Layout Handling

  • Empty Data: Card hidden if isEmptyData is true
  • Hero Mode: Special rendering via isHero flag
  • No Headings: Content area adjusts spacing when headings hidden

Comparison: Toplist vs Toplist2 vs Toplist3

Feature Toplist3 Toplist (Puzzle) Toplist2
Layout Card grid (3/2/1 columns) Table rows CSS Grid (6/4/1 columns)
Max Brands 9 (recommended) Unlimited Unlimited
Social Proof Ribbons Yes (with icons) No No
Ranking Display No explicit numbers No Numbered badges (01-99)
Card Styling Shadow + hover effects No cards No cards
Grid Responsiveness 3→2→1 columns Table → single column 6→4→1 columns
Bonus Control 3 flags (all, ribbon, text) 2 flags (ribbon, text) 3 flags
CTA Customization Full gradient control Limited Limited
Hero Mode Yes (special rendering) No No
Checklist No Yes (desktop only) No
Use Case Category pages, featured lists Comparison tables Ranked comparisons

Backward Compatibility

Legacy Tag Support

Fully supports legacy bw-widget tag:

<bw-widget id="toplist3" ...></bw-widget>

Dual Naming Convention Support

Both old and new attribute naming conventions work:

Old Convention (hyphenated):

  • selling-point-type
  • max-rows
  • cta-key
  • cta-text
  • heading-level
  • heading-alignment
  • heading-text
  • heading-key
  • bonus-type
  • min-width
  • cta-colors
  • cta-hover-colors
  • show-sub-heading
  • intro-text-alignment
  • eager-count

New Convention (camelCase/lowercase):

  • sellingpointtype
  • maxrows
  • ctakey
  • ctatext
  • headinglevel
  • headingalignment
  • headingtext
  • headingkey
  • bonustype
  • minwidth
  • ctacolors
  • ctahovercolors
  • showsubheading
  • introtextalignment
  • eagercount

CTA Color Format Flexibility

Supports multiple formats for colors:

  • JSON arrays: '["#color1", "#color2"]'
  • Single colors: 'green' or '#05842A'
  • Named colors: 'red', 'blue', etc.

Configuration Stability

Widget behavior stable across both naming conventions.