---
title: "Customizing Widgets"
canonical_url: "https://apidocs.sportradar.com/resources/widgets/docs/tutorials/widgets-customization"
markdown_url: "https://apidocs.sportradar.com/resources/widgets/docs/tutorials/widgets-customization.md"
last_updated: "2026-07-29T06:31:14Z"
---
# Customizing Widgets
Component-level customization for Sportradar widgets is provided through the `branding` configuration object. This reference documents all available properties and their usage patterns.
## Overview
The branding object allows you to:
- Customize tab appearance and behavior across widgets
- Replace default icons with custom assets
- Apply widget-specific configurations through namespaces
- Maintain consistent visual identity across your integration
> **Note**
>
> For full widget theming (colors, fonts, etc.), see the [Theming Guide](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/theming-widgets.md). For tab-specific customization examples, see [Customizing Tabs Tutorial](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/examples/customizing-tabs.md).
## Branding Object Structure
The branding object follows this hierarchical structure:
```typescript
{
tabs?: TabsConfiguration,
sports?: SportsConfiguration,
events?: EventsConfiguration,
namespaces?: NamespacesConfiguration
}
```
### Basic Usage Example
```javascript
SIR("addWidget", ".sr-widget-1", "match.preview", {
matchId: "sr:match:12345",
branding: {
tabs: {
option: 'iconText',
align: 'center'
},
namespaces: {
avTabSwitcher: {
tabs: {
useClientTheming: true
}
}
}
}
});
```
## Top-Level Properties
### `tabs` {#tabs}
Global tab configuration applied to all tab components within the widget.
**Type:** `TabsConfiguration`
```typescript
type TabsConfiguration = {
option?: 'iconText' | 'icon' | 'text';
align?: 'start' | 'center' | 'end';
iconPosition?: 'start' | 'end';
variant?: 'fullWidth' | 'standard';
icons?: { [tabName: string]: string | ReactElement };
arrowIcon?: string | ReactElement;
useClientTheming?: boolean;
}
```
| Property | Type | Default | Description |
| ------------------ | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `option` | `'iconText' \| 'icon' \| 'text'` | `'iconText'` | Display mode for tabs. Controls whether icons, text, or both are shown. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Horizontal alignment of tabs within the container. |
| `iconPosition` | `'start' \| 'end'` | `'start'` | Position of icon relative to text (when `option` is `'iconText'`). |
| `variant` | `'fullWidth' \| 'standard'` | `'standard'` | Tab layout style. `'fullWidth'` stretches tabs to fill container width. |
| `icons` | `object` | `{}` | Custom icon mapping. Keys are tab names (e.g., `'overview'`, `'statistics'`), values are icon URLs or React elements. |
| `arrowIcon` | `string \| ReactElement` | Built-in arrow | Custom arrow icon for tab navigation/scrolling. |
| `useClientTheming` | `boolean` | `false` | Enable CSS-based theming from client styles instead of built-in theme. When `true`, default styles are removed and `.srct-` prefixed CSS classes are applied. See [Customizing Tabs](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/examples/customizing-tabs.md#css-selectors) for available class names. |
**Example:**
```javascript
branding: {
tabs: {
option: 'iconText',
align: 'center',
iconPosition: 'end',
variant: 'fullWidth',
icons: {
overview: 'https://example.com/overview-icon.svg',
statistics: '',
timeline: 'data:image/svg+xml;base64,...'
},
arrowIcon: 'https://example.com/custom-arrow.svg',
useClientTheming: true
}
}
```
### `sports` {#sports}
Sport-specific icon configuration, typically used in widgets displaying multiple sports.
**Type:** `SportsConfiguration`
```typescript
type SportsConfiguration = {
icons?: {
[sportId: string]: string | ReactElement;
default?: string | ReactElement;
}
}
```
| Property | Type | Description |
| -------- | -------- | ---------------------------------------------------------------------------- |
| `icons` | `object` | Map of sport IDs to icon assets. Supports a `default` key for fallback icon. |
**Example:**
```javascript
branding: {
sports: {
icons: {
'1': 'https://example.com/soccer.svg', // Soccer
'2': 'https://example.com/basketball.svg', // Basketball
'5': 'https://example.com/tennis.svg', // Tennis
'default': 'https://example.com/sport.svg' // Fallback
}
}
}
```
> **Tip**
>
> Common sport IDs: Soccer (1), Basketball (2), Baseball (3), Ice Hockey (4), Tennis (5), Handball (6), American Football (16). See complete list in [Sport IDs Reference](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/references/sports.md).
### `events` {#events}
Event-specific icon and label configuration for match events.
**Type:** `EventsConfiguration`
```typescript
type EventsConfiguration = {
icons?: {
[eventName: string]: {
icon: string;
label: string;
}
}
}
```
| Property | Type | Description |
| -------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `icons` | `object` | Map of event names to icon configuration objects containing `icon` (URL/path) and `label` (alt text). |
**Example:**
```javascript
branding: {
events: {
icons: {
'goal': {
icon: 'https://example.com/goal-icon.svg',
label: 'Goal scored'
},
'yellowCard': {
icon: 'https://example.com/yellow-card.svg',
label: 'Yellow card'
}
}
}
}
```
### `namespaces` {#namespaces}
Widget-specific or component-specific configuration overrides. Namespaces allow fine-grained control over individual widget components.
**Type:** `NamespacesConfiguration`
```typescript
type NamespacesConfiguration = {
[namespaceName: string]: {
tabs?: TabsConfiguration;
icons?: {
[iconName: string]: {
icon: string;
label: string;
}
}
}
}
```
**Common Namespaces:**
| Namespace | Used In | Purpose |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avTabSwitcher` | Live Match Tracker (LMT) | Audio/Video tab switcher configuration |
| `virtualStadium` | Virtual Stadium | Virtual Stadium widget icons and settings |
| `sports` | Bet Recommendation and multi-sport widgets | Sport icon overrides within a specific widget context |
| `avStreamToggle` | LMT with streaming | Stream toggle button configuration. See [On-Pitch Stream Toggle](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/widget-specific/component-on-pitch-lco-stream-toggle.md) for available icon IDs and CSS classes. |
**Example:**
```javascript
branding: {
tabs: {
// Global tab settings
option: 'iconText',
align: 'start'
},
namespaces: {
avTabSwitcher: {
tabs: {
// Override global settings for AV tab switcher
option: 'icon',
align: 'center',
useClientTheming: true
}
},
virtualStadium: {
icons: {
'send': {
icon: 'https://example.com/send-button.svg',
label: 'Send message'
},
'close': {
icon: 'https://example.com/close.svg',
label: 'Close'
}
}
}
}
}
```
## Configuration Hierarchy
Settings follow this priority order (highest to lowest):
1. **Namespace-specific settings** - `branding.namespaces.[namespace].tabs`
2. **Global branding settings** - `branding.tabs`
3. **Widget defaults** - Built-in default values
This allows you to set global defaults and override them per-component as needed.
## Tab Name Reference
The following tab names can be used in the `tabs.icons` configuration:
| Tab Name | Used In Widgets | Description |
| ---------------- | --------------------------------- | ------------------------------- |
| `overview` | Match Preview, LMT | General match overview/summary |
| `statistics` | Match Preview, LMT | Match statistics and team stats |
| `timeline` | LMT | Match timeline/events |
| `lineups` | Match Preview, LMT | Team lineups and formations |
| `headToHead` | Match Preview, Head to Head | Head-to-head comparison |
| `standings` | Match Preview, Tournament | League/tournament standings |
| `form` | Match Preview | Team form guide |
| `teams` | Tournament Preview | Teams in tournament |
| `cup` | Tournament Preview | Cup/knockout stage bracket |
| `playoffs` | Tournament Preview | Playoff bracket |
| `boxScore` | LMT (Basketball, Baseball) | Box score statistics |
| `plays` | LMT (American Football) | Play-by-play listing |
| `roster` | Team widgets | Team roster |
| `probabilities` | LMT | Win probabilities |
| `matchInfo` | LMT | Detailed match information |
| `avStream` | Live Match Tracker | Audio/Video stream tab |
| `scoreboard` | LMT | Scoreboard view |
| `commentary` | Match Preview, LMT | Live match commentary |
| `injuries` | Match Preview, LMT (NBA) | Team injury reports |
| `topScorers` | Tournament Preview, Match Preview | Top goal/point scorers |
| `fixtures` | Tournament Preview | Upcoming match fixtures |
| `results` | Tournament Preview | Past match results |
| `winProbability` | Match Preview, LMT | Win probability chart |
| `momentum` | LMT | Match momentum visualization |
| `heatMap` | LMT (Basketball) | Player heat map |
| `gamePulse` | LMT | Live game pulse indicator |
| `playerStats` | LMT (NBA, Basketball) | Individual player statistics |
| `teamInfo` | Match Preview | Team information and details |
## Icon Format Requirements
Icons provided in the branding object must meet these requirements:
### Supported Formats
- **SVG** - Recommended for scalability
- Inline SVG strings
- SVG file URLs
- Data URLs (`data:image/svg+xml;base64,...`)
- **PNG** - For raster graphics
- Transparent background recommended
- Minimum 24×24px, recommended 48×48px for high-DPI displays
- **React Elements** - For programmatic icons (SVG components)
### SVG Requirements
When providing SVG files or inline SVG, ensure:
1. **Root element has `id="icon"`** (for some widget types)
```xml
```
2. **Proper viewBox** for scaling
3. **No hardcoded colors** if you want CSS theming to apply
> **Warning**
>
> Always test custom icons in different widget states (active, inactive, hover) to ensure proper visibility against various backgrounds.
## Complete Integration Example
Here's a comprehensive example showing multiple branding features:
```javascript
SIR("addWidget", ".sr-lmt-widget", "match.lmtplus", {
matchId: "sr:match:12345",
// Widget-specific properties
enableAudioVideo: true,
// Branding configuration
branding: {
// Global tab settings
tabs: {
option: 'iconText',
align: 'center',
variant: 'fullWidth',
iconPosition: 'start',
useClientTheming: false,
icons: {
overview: 'https://cdn.example.com/icons/overview.svg',
statistics: 'https://cdn.example.com/icons/stats.svg',
timeline: 'https://cdn.example.com/icons/timeline.svg',
lineups: 'https://cdn.example.com/icons/lineups.svg'
},
arrowIcon: 'https://cdn.example.com/icons/arrow-right.svg'
},
// Sport icons for multi-sport widgets
sports: {
icons: {
'1': 'https://cdn.example.com/sports/soccer.svg',
'2': 'https://cdn.example.com/sports/basketball.svg',
'default': 'https://cdn.example.com/sports/generic.svg'
}
},
// Match event icons
events: {
icons: {
'goal': {
icon: 'https://cdn.example.com/events/goal.svg',
label: 'Goal'
},
'yellowCard': {
icon: 'https://cdn.example.com/events/yellow.svg',
label: 'Yellow Card'
}
}
},
// Component-specific overrides
namespaces: {
avTabSwitcher: {
tabs: {
// Override for audio/video tab switcher
option: 'icon',
align: 'end',
useClientTheming: true,
icons: {
avStream: 'https://cdn.example.com/icons/video.svg'
}
}
}
}
}
});
```
## Widget-Specific Documentation
For detailed information about specific widget implementations:
- **Tab Customization**: [Customizing Widget Tabs](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/examples/customizing-tabs.md)
- **Theme Customization**: [Theming Widgets](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/theming-widgets.md)
- **LMT Audio/Video Toggle**: [On-Pitch Stream Toggle](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/widget-specific/component-on-pitch-lco-stream-toggle.md)
- **Event Tracking**: [Tracking Guide](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/tracking-guide.md)
## Troubleshooting
### Icons Not Displaying
**Problem:** Custom icons don't appear in the widget.
**Solutions:**
- Verify icon URLs are publicly accessible (check CORS settings)
- Ensure icon file format is supported (SVG, PNG)
- Check browser console for 404 or CORS errors
- For SVG, verify proper XML syntax and `id="icon"` attribute if required
- Test with absolute URLs before using relative paths
### Tabs Not Applying Configuration
**Problem:** Tab settings in branding object are ignored.
**Solutions:**
- Check if the tab name matches exactly (case-sensitive)
- Verify the widget you're using actually contains those tabs
- Try setting `useClientTheming: false` to use built-in theming
- Check for namespace-specific overrides that might conflict
### Namespace Settings Not Working
**Problem:** Namespace configuration doesn't take effect.
**Solutions:**
- Confirm correct namespace name for your widget
- Check widget documentation for supported namespaces
- Ensure namespace settings are nested properly under `branding.namespaces`
- Verify the specific widget version supports namespace customization
## Type Definitions
For TypeScript users, here are the complete type definitions:
```typescript
type TabsConfiguration = {
option?: 'iconText' | 'icon' | 'text';
align?: 'start' | 'center' | 'end';
iconPosition?: 'start' | 'end';
variant?: 'fullWidth' | 'standard';
icons?: { [key: string]: string | React.ReactElement };
arrowIcon?: string | React.ReactElement;
useClientTheming?: boolean;
};
type BrandingConfiguration = {
tabs?: TabsConfiguration;
sports?: {
icons?: {
[sportId: string]: string | React.ReactElement;
};
};
events?: {
icons?: {
[eventName: string]: {
icon: string;
label: string;
};
};
};
namespaces?: {
[namespaceName: string]: {
tabs?: TabsConfiguration;
icons?: {
[iconName: string]: {
icon: string;
label: string;
};
};
};
};
};
```
## Further Reading
- [Widget Integration Guide](https://apidocs.sportradar.com/resources/widgets.md) - Getting started with widget integration
- [SIR Reference](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/SIR.md) - Complete SIR API documentation
- [Theming Widgets](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/theming-widgets.md) - Global theming and styling
- [Customizing Tabs Tutorial](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/examples/customizing-tabs.md) - Step-by-step tab customization