Events

Handle events and callbacks from the Metreek SDK components.

The SDK uses a pub/sub event system. You can listen to events at the SDK level or directly on components.

SDK Events

Listen to SDK-level events using MetreekSDK.on():

JavaScript
// Listen to SDK initialization
MetreekSDK.on('sdk:initialized', () => {
  console.log('SDK is ready!')
})

// Listen to errors
MetreekSDK.on('sdk:error', (event) => {
  console.error('SDK Error:', event.detail.error)
})
EventDescription
sdk:initializedSDK has finished initializing
sdk:errorSDK encountered an error
component:registeredA component was registered in the DOM

Chat Events

Listen to chat events directly on the component:

JavaScript
const chat = document.querySelector('metreek-chat')

// Message events
chat.addEventListener('message:sent', (e) => {
  console.log('User sent:', e.detail.message)
})

chat.addEventListener('message:received', (e) => {
  console.log('AI replied:', e.detail.message)
})

// Streaming progress
chat.addEventListener('stream:progress', (e) => {
  console.log('Step:', e.detail.step, 'Progress:', e.detail.progress)
})

// Chat open/close
chat.addEventListener('chat:opened', () => {
  console.log('Chat opened')
})

chat.addEventListener('chat:closed', () => {
  console.log('Chat closed')
})
EventDetailDescription
chat:opened{ chatId }Chat window opened
chat:closed{ chatId }Chat window closed
message:sent{ messageId, message }User sent a message
message:received{ messageId, message }AI response received
stream:progress{ messageId, step, progress }Stream processing update
stream:completed{ messageId }Stream finished
error{ error, context }Error occurred

Widget Events

Listen to widget events directly on the component:

JavaScript
const widget = document.querySelector('#my-widget')

// Data loaded
widget.addEventListener('widget:loaded', (e) => {
  console.log('Widget loaded:', e.detail.widgetId)
})

// Chart interactions
widget.addEventListener('chart:click', (e) => {
  console.log('Clicked:', e.detail.params)
  // e.detail.params contains ECharts click event data
})

// Error handling
widget.addEventListener('widget:error', (e) => {
  console.error('Widget error:', e.detail.error)
})
EventDetailDescription
widget:loaded{ widgetId, blockId }Widget data loaded successfully
widget:error{ widgetId, error }Widget failed to load
widget:refreshed{ widgetId }Widget data refreshed
chart:click{ widgetId, params }User clicked on chart element
chart:rendered{ widgetId }Chart finished rendering

State Events

The SDK's internal state manager emits events when state changes:

JavaScript
// Listen to any state change
MetreekSDK.on('state:changed', (event) => {
  console.log('State changed:', {
    key: event.detail.key,
    oldValue: event.detail.oldValue,
    newValue: event.detail.newValue
  })
})
EventDescription
state:changedAny state value changed
state:clearedState was cleared

Removing Listeners

Always clean up event listeners when they're no longer needed:

JavaScript
// Store reference to handler
const messageHandler = (e) => {
  console.log('Message:', e.detail)
}

// Add listener
MetreekSDK.on('message:received', messageHandler)

// Remove listener when done
MetreekSDK.off('message:received', messageHandler)

// Or for component events
const widget = document.querySelector('#my-widget')
widget.addEventListener('widget:loaded', messageHandler)
widget.removeEventListener('widget:loaded', messageHandler)

Best Practice

In frameworks like React or Vue, remove event listeners in cleanup functions (useEffect cleanup, onUnmounted) to prevent memory leaks.