ticketmaster-venue-widget

Embeddable Ticketmaster events widget for venue websites. Displays upcoming events in a responsive grid with filtering, pagination, and detail modals. Easy integration with Squarespace and other platforms via CDN.

Quick Start

Add the CSS and JS from the CDN, then drop a <div> with data attributes:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ticketmaster-venue-widget@1/dist/ticketmaster-venue-widget.min.css" />

<div
  data-venue-events
  data-api-key="YOUR_API_KEY"
  data-venue-id="VENUE_ID"
  data-limit="12"
  data-columns="3">
</div>

<script src="https://cdn.jsdelivr.net/npm/ticketmaster-venue-widget@1/dist/ticketmaster-venue-widget.min.js"></script>

The widget auto-initializes on any element with data-venue-events.

JavaScript Initialization

For more control, initialize via JS instead of (or alongside) data attributes:

<div id="events" data-venue-events></div>

<script src="https://cdn.jsdelivr.net/npm/ticketmaster-venue-widget@1/dist/ticketmaster-venue-widget.min.js"></script>
<script>
  VenueEvents.init({
    apiKey: 'YOUR_API_KEY',
    venues: ['VENUE_ID_1', 'VENUE_ID_2'],
    defaultLimit: 12,
    subVenues: {
      'VENUE_ID_2': 'Side Stage'
    },
    theme: {
      '--ve-primary': '#2d3b97',
      '--ve-background': '#fbf6df'
    },
    modal: {
      sections: ['image', 'info', 'description', 'startTime', 'venue', 'price', 'genre', 'performers'],
      timeDisplay: 'inline'
    }
  });
</script>

Config passed to init() is deep-merged with defaults for the modal, tracking, and cacheDuration sub-objects. All other keys are shallow-merged (user value replaces default).

Configuration Reference

All keys and their defaults from DEFAULT_CONFIG:

| Key | Type | Default | Description | |-----|------|---------|-------------| | apiKey | string | null | Ticketmaster Discovery API key (required unless using proxyUrl) | | venues | string[] | [] | Array of Ticketmaster venue IDs | | baseUrl | string | "https://app.ticketmaster.com/discovery/v2" | API base URL | | defaultLimit | number | 12 | Number of events to fetch per page | | cacheEnabled | boolean | true | Enable client-side caching | | cacheDuration | object | see below | Cache TTLs per resource type | | debug | boolean | false | Log debug info to console | | promoterId | string | null | Ticketmaster promoter ID for merged results | | subVenues | object | null | Map of venue ID to display name (e.g. { 'ID': 'Side Stage' }) | | theme | object | null | CSS custom property overrides (e.g. { '--ve-primary': '#333' }) | | proxyUrl | string | null | Proxy endpoint URL (hides API key from client) | | tracking | object | see below | UTM tracking config | | modal | object | see below | Event detail modal config |

cacheDuration defaults

| Key | Default | Duration | |-----|---------|----------| | events | 3600000 | 1 hour | | venues | 86400000 | 24 hours | | classifications | 604800000 | 7 days | | search | 900000 | 15 minutes |

tracking defaults

| Key | Type | Default | Description | |-----|------|---------|-------------| | enabled | boolean | false | Enable UTM tracking on ticket links | | utmSource | string | "venue_website" | UTM source parameter | | utmMedium | string | "referral" | UTM medium parameter | | utmCampaign | string | "events_widget" | UTM campaign parameter |

Modal Configuration

The modal object controls the event detail modal:

| Key | Type | Default | Description | |-----|------|---------|-------------| | enabled | boolean | true | Show modal on event click | | sections | string[] | see below | Sections to render, in order | | timeDisplay | string | "inline" | Time display mode: "inline", "doors", or "none" | | showVenueAddress | boolean | true | Show street address in venue section | | showVenueCity | boolean | true | Show city in venue section | | startTimeLabel | string | "Start Time" | Label for start time row | | doorsOffsetMinutes | number | 0 | Minutes to subtract from start time for doors-open time |

Available sections

The sections array controls which sections appear and in what order. Available values:

| Section | Description | |---------|-------------| | image | Event image | | info | Event name, date, and time summary | | description | Full event description text | | pleaseNote | "Please Note" text from Ticketmaster | | startTime | Start time / doors time row | | ageRestriction | Age restriction info | | venue | Venue name, address, city | | price | Price range | | genre | Genre / classification tags | | performers | Performer / attraction list |

Default sections (in order):

image, info, description, pleaseNote, startTime, venue, price, genre, performers

Data Attributes Reference

All data attributes supported on data-venue-events elements:

Global config (read from the first data-venue-events element)

| Data Attribute | Config Key | Notes | |----------------|------------|-------| | data-api-key | apiKey | | | data-venue-id | venues | Comma-separated venue IDs | | data-limit | defaultLimit | | | data-debug | debug | "true" to enable | | data-promoter-id | promoterId | | | data-proxy-url | proxyUrl | |

Theme

| Data Attribute | CSS Variable | |----------------|-------------| | data-theme-primary | --ve-primary | | data-theme-primary-hover | --ve-primary-hover | | data-theme-bg | --ve-background |

Tracking

| Data Attribute | Config Key | |----------------|------------| | data-tracking | tracking.enabled ("true" to enable) | | data-utm-source | tracking.utmSource | | data-utm-medium | tracking.utmMedium | | data-utm-campaign | tracking.utmCampaign |

Modal

| Data Attribute | Config Key | Notes | |----------------|------------|-------| | data-modal-enabled | modal.enabled | "false" to disable | | data-modal-sections | modal.sections | Comma-separated section names | | data-modal-time-display | modal.timeDisplay | "inline", "doors", or "none" | | data-modal-show-venue-address | modal.showVenueAddress | "false" to hide | | data-modal-show-venue-city | modal.showVenueCity | "false" to hide | | data-modal-start-time-label | modal.startTimeLabel | | | data-modal-doors-offset-minutes | modal.doorsOffsetMinutes | Integer |

Per-widget options (on each data-venue-events element)

| Data Attribute | Default | Notes | |----------------|---------|-------| | data-venue-id | from config | Comma-separated; overrides global venues | | data-limit | 12 | | | data-layout | "grid" | "grid" or "list" | | data-columns | 3 | Grid columns (responsive: 2 at 1024px, 1 at 640px) | | data-card-style | "default" | "default", "compact", or "detailed" | | data-show-filters | false | "true" to enable date/keyword filters | | data-show-venue-filter | false | "true" to enable venue dropdown | | data-show-pagination | true | "false" to hide | | data-show-genre | false | "true" to show genre on cards |

Curated strip — [data-ve-curated]

A horizontal carousel of handpicked events. Supports fewer visible columns than total rendered so extra cards are reachable via swipe / arrows / dots.

Venue configuration comes from the root VenueEvents.init({ venues: [...] }) call, not from a per-element attribute.

| Data Attribute | Default | Notes | |---|---|---| | data-count | 4 | Total events rendered on the carousel track | | data-columns | data-count | Cards visible per row on wide viewports; CSS steps down to 2 at ≤768px and 1 at ≤640px | | data-label | "Featured Events" | Heading text | | data-heading | "p" | Heading tag (h1–h6, p) | | data-option | "upcoming" | "upcoming" or "recently-added" | | data-ids | — | Comma-separated event IDs (overrides option) | | data-show-venue-label | true | "false" to hide venue name on cards | | data-show-price | true | "false" to hide price on cards | | data-show-genre | false | "true" to show genre on cards |

Example:

<div data-ve-curated
     data-count="5"
     data-columns="3"
     data-label="Featured Events">
</div>

Theming

Override any CSS custom property via the theme config object or inline on the container:

Colors

| Variable | Default | |----------|---------| | --ve-primary | #e63946 | | --ve-primary-hover | #d62839 | | --ve-text | #1a1a1a | | --ve-text-muted | #666666 | | --ve-background | #ffffff | | --ve-card-bg | #ffffff | | --ve-border | #e5e5e5 | | --ve-shadow | rgba(0, 0, 0, 0.1) |

Typography

| Variable | Default | |----------|---------| | --ve-font-family | inherit | | --ve-font-size-sm | 0.875rem | | --ve-font-size-base | 1rem | | --ve-font-size-lg | 1.125rem | | --ve-font-size-xl | 1.25rem | | --ve-font-weight-normal | 400 | | --ve-font-weight-medium | 500 | | --ve-font-weight-bold | 600 |

Spacing

| Variable | Default | |----------|---------| | --ve-spacing-xs | 0.25rem | | --ve-spacing-sm | 0.5rem | | --ve-spacing-md | 1rem | | --ve-spacing-lg | 1.5rem | | --ve-spacing-xl | 2rem |

Layout

| Variable | Default | |----------|---------| | --ve-card-radius | 8px | | --ve-input-radius | 4px | | --ve-transition | 0.2s ease | | --ve-columns | 3 |

Buttons

| Variable | Default | |----------|---------| | --ve-button-radius | 4px | | --ve-button-text-transform | none | | --ve-button-letter-spacing | 0 | | --ve-button-font-weight | 500 |

Example via JS:

VenueEvents.init({
  apiKey: 'YOUR_KEY',
  venues: ['VENUE_ID'],
  theme: {
    '--ve-primary': '#2d3b97',
    '--ve-primary-hover': '#232e78',
    '--ve-background': '#fbf6df',
    '--ve-card-radius': '12px'
  }
});

Example via data attributes:

<div data-venue-events
     data-api-key="YOUR_KEY"
     data-venue-id="VENUE_ID"
     data-theme-primary="#2d3b97"
     data-theme-bg="#fbf6df">
</div>

Proxy Mode

To keep your API key off the client, point the widget at a proxy endpoint:

<div data-venue-events
     data-proxy-url="https://your-proxy.example.com"
     data-api-key="placeholder"
     data-venue-id="VENUE_ID">
</div>

The widget sends requests to proxyUrl instead of the Ticketmaster API directly. Your proxy is responsible for injecting the real API key and forwarding to https://app.ticketmaster.com/discovery/v2. A data-api-key value is still required (it passes the config guard) but is never sent to Ticketmaster.

Standalone Build

Produce a single self-contained .js file with CSS inlined and config baked in. Upload it directly to Squarespace or any website — no CDN, no external CSS, no proxy required.

npm run build:standalone -- --config configs/example.json --out dist/my-venue.min.js

The config JSON matches the VenueEvents.init() options documented above. See configs/example.json for the full structure.

Options

| Flag | Required | Description | |------|----------|-------------| | --config <path\|json> | Yes | Path to a JSON config file, or an inline JSON string | | --out <path> | No | Output file path (default: dist/standalone.min.js) | | --no-minify | No | Skip Terser minification (useful for debugging) |

Example: inline JSON config

node scripts/build-standalone.js \
  --config '{"apiKey":"abc123","venues":["KovZpZAJledA"],"defaultLimit":6}' \
  --out dist/venue.min.js

Testing a standalone build

Open test-standalone.html in a browser after building to dist/standalone-test.min.js. No server required.

Development

npm install
npm run build          # Build dist/ (minified + dev)
npm run watch          # Rebuild on file changes
npm run serve          # Start local server on :8080

Open http://localhost:8080/test.html to test all widget features. The test page includes:

• Test 1a/2a — Default config with all modal sections visible
• Test 1b/2b — Custom config demonstrating venue-specific overrides
• Test 3 — Proxy mode (requires a local worker on :8787)

Build output

| File | Purpose | |------|---------| | dist/ticketmaster-venue-widget.min.js | Production JS (minified) | | dist/ticketmaster-venue-widget.min.css | Production CSS (minified) | | dist/venue-events.js | Development JS | | dist/venue-events.css | Development CSS | | dist/embed.html | Self-contained embed (CSS + JS inline) |

License

MIT