Calendar Widget Documentation

Quick Start

The easiest way to use the calendar widget is via the global calendar_listing function:

// Get a reference to a DOM element
const root = document.getElementById('calendar-listing')

// Initialize the widget
const widget = calendar_listing(root, {
  api_url: 'https://example.com',
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

// Later, to clean up:
widget.cleanup()

Live Demo

Installation

Option 1: ES Module Import

import { calendar_listing } from 'https://example.com/widget.es.js'

const root = document.getElementById('calendar-root')
calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Option 2: SolidJS Integration

For SolidJS applications, import the component directly:

import { CalendarView, CalendarCriteria } from 'https://example.com/widget.es.js'

function MyComponent() {
  const criteria: CalendarCriteria = {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }

  return (
    <div>
      <CalendarView criteria={criteria} />
    </div>
  )
}

API Reference

calendar_listing(root, props)

Render a calendar widget into the specified DOM element.

Parameter	Type	Required	Description
`root`	HTMLElement	Required	The DOM element to render the widget into
`props`	CalendarViewProps	Optional	Configuration options for the widget

Returns: `WidgetInstance`

Property	Type	Description
`cleanup()`	function	Removes the widget and cleans up resources

CalendarViewProps

Configuration options for the calendar widget.

Property	Type	Default	Description
`api_url`	string	BASE_URL	Base URL for the calendar API
`criteria`	CalendarCriteria	{}	Filters and search criteria for events
`show_header`	boolean	false	Show the calendar header with date picker and controls

CalendarCriteria

Filter criteria for calendar events. All fields are optional.

Property	Type	Description
`by_category`	number \| null	Filter by category ID
`by_location`	string \| null	Filter by location code (e.g., 'US', 'UK', 'EU')
`text_query`	string \| null	Search events by text content
`by_classification`	Classification	Filter by event type: 'data', 'holiday', 'ad_hoc', 'expiry', 'speaker', 'supply', 'earning'
`occurs_from`	string \| null	Start date for date range filter (ISO format)
`occurs_to`	string \| null	End date for date range filter (ISO format)

Examples

Filter by Date Range

const widget = calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

Filter by Category

// Show only events from category ID 5
const widget = calendar_listing(root, {
  criteria: { by_category: 5 }
})

Filter by Location

// Show only US events
const widget = calendar_listing(root, {
  criteria: { by_location: 'US' }
})

// Show G20 major economies
const g20 = ['US', 'GB', 'EU', 'JP', 'DE', 'CN', 'FR', 'IT', 'CA', 'AU']
// Note: Use multiple widget instances or broader criteria for multiple locations

Search by Text

// Search for events containing "GDP"
const widget = calendar_listing(root, {
  criteria: { text_query: 'GDP' }
})

Filter by Event Type

// Show only economic data releases
const widget = calendar_listing(root, {
  criteria: { by_classification: 'data' }
})

// Show only holidays
const widget = calendar_listing(root, {
  criteria: { by_classification: 'holiday' }
})

Combined Filters

// Show US economic data for today
const widget = calendar_listing(root, {
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z',
    by_location: 'US',
    by_classification: 'data'
  }
})

Custom API Endpoint

const widget = calendar_listing(root, {
  api_url: 'https://example.com/api',
  criteria: {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z'
  }
})

SolidJS Integration

For SolidJS applications, you can import the component and types directly:

import {
  CalendarView,
  CalendarCriteria,
  CalendarViewProps,
  CalendarEvent,
  Classification
} from 'https://example.com/widget.es.js'

// Use in your component
function App() {
  const criteria: CalendarCriteria = {
    occurs_from: '2025-12-18T00:00:00.000Z',
    occurs_to: '2025-12-18T23:59:59.999Z',
    by_classification: 'data'
  }

  const props: CalendarViewProps = {
    api_url: 'https://example.com',
    criteria
  }

  return <CalendarView {...props} />
}

Available Exports

Export	Type	Description
`calendar_listing`	function	Framework-agnostic widget initializer
`CalendarView`	Component	SolidJS component for direct use
`CalendarViewProps`	interface	TypeScript interface for component props
`CalendarCriteria`	interface	TypeScript interface for filter criteria
`CalendarEvent`	type	Type for calendar event objects
`Classification`	type	Union type for event classifications
`create_calendar_store`	function	Low-level store for custom integrations