Toplist3 (Toplist v3)

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

<nw-blocks id="toplist3" sellingpointtype="general" product="CA" country="ZZ" language="en" maxrows="4" 
  ctakey="cta-claim-bonus" 
  ctatext="Claim Bonus" 
  headingtext="Best Online Casinos" 
  headinglevel="h2" 
  headingalignment="center" 
  introtext="Discover top-rated casinos with exclusive bonuses" 
  introtextalignment="center" 
  ctacolors='["#05842A", "#05842A"]' 
  ctahovercolors='["#096725", "#096725"]' 
  trackinglinktarget="homepage" 
  target="_blank"
  anchorid="testanchorshowcasegithubtoplist3"
  rel="nofollow" \>
</nw-blocks>

404: toplist3, cfRayID a0e512414b857f3b, short: undefined, product: CA, country: ZZ, language: en, currency: EUR

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

<nw-blocks id="toplist3" selling-point-type="general" language="fr" product="CA" min-width="180px" max-rows="2" 
  show-sub-heading="true" 
  heading-text="Top 2 Casinos"
  heading-level="3"
  heading-alignment="left"
  anchorid="testanchorshowcasegithubtoplist3"
  introtext="Custom intro text for top casinos"
  introtextalignment="left" \>
</nw-blocks>

Toplist3 Standard Layout (Container Width > 600px)

<nw-blocks id="toplist3" sellingpointtype="general" language="fr" product="CA" maxrows="6" \>
</nw-blocks>

Toplist3 with No Deposit Bonus Filter

<nw-blocks id="toplist3" sellingpointtype="general" bonustype="ndb" product="CA" language="fr" maxrows="5" 
  ctakey="cta-claim-bonus"
  ctatext="Claim No Deposit Bonus" \>
</nw-blocks>

404: toplist3, cfRayID a0e512414b857f3b, short: undefined, product: CA, country: US, language: fr, currency: EUR

Toplist3 for Sportsbook Product

<nw-blocks id="toplist3" sellingpointtype="general" product="SB" language="en" maxrows="6" 
  ctakey="cta-bet-now"
  ctatext="Bet Now" \>
</nw-blocks>

404: toplist3, cfRayID a0e512414b857f3b, short: undefined, product: SB, country: US, language: fr, currency: EUR

Toplist3 with Custom CTA Colors

<nw-blocks 
  id="toplist3" sellingpointtype="general" product="SB" language="en" maxrows="4" 
  ctakey="cta-bet-on-game"
  ctacolors='["#0066cc", "#004499"]'
  ctahovercolors='["#004499", "#002266"]' \>
</nw-blocks>

404: toplist3, cfRayID a0e512414b857f3b, short: undefined, product: SB, country: US, language: fr, currency: EUR

Attributes Reference

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

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.