---
title: Handling DOM Events
description: Handle DOM events with bodyAttrs for window resize, online/offline status, page lifecycle, and print events. Use onload/onerror for stylesheets.
navigation.title: DOM Event Handling
---

**Quick Answer:** Use `onload` and `onerror` attributes in your `useHead()` script tags. For advanced event handling, use `useScript()` with `onLoaded()` and `onError()` callbacks. For window/document events, use `bodyAttrs` with event handlers like `onresize` or `ononline`.

## What is DOM Event Handling in Unhead?

Unhead provides support for native DOM event handling, allowing you to attach event listeners to document elements through head management. This feature enables you to execute code in response to various browser events like window resizing, navigation changes, or print events.

::note
This guide focuses on non-script DOM events, particularly those attached to the body element. For script-specific event handling and loading, please refer to the [Loading Scripts](/docs/head/guides/core-concepts/loading-scripts) guide which covers the more powerful [`useScript()`](/docs/head/api/composables/use-script) composable.
::

## How Do I Handle Stylesheet Load Events?

For non-script resources like stylesheets, Unhead supports standard HTTP-related events. Use `onload` to detect when a stylesheet has finished loading, and `onerror` to handle failures.

```ts
import { useHead } from '@unhead/dynamic-import'

// useHead: /docs/head/api/composables/use-head
if (import.meta.client) {
  useHead({
    link: [
      {
        rel: 'stylesheet',
        href: '/assets/critical.css',
        onload: () => {
          console.log('Critical CSS loaded')
          // Load non-critical resources
          loadDeferredResources()
        },
        onerror: () => {
          console.error('Failed to load stylesheet - using fallback styles')
          applyFallbackStyles()
        }
      }
    ]
  }, { mode: 'client' })
}
```

::note
Remember that stylesheet events should also be used with `{ mode: 'client' }` to ensure they work correctly with SSR.
::

## How Do I Listen to Window and Document Events?

Unhead allows you to attach event handlers to the document body through the `bodyAttrs` property. These events effectively let you respond to document and window-level events.

::note
Per the HTML specification, body event handlers are automatically proxied to the `window` object for better browser compatibility.
::

### What Body Events Are Supported?

These events are only supported with `bodyAttrs` and provide access to various browser lifecycle events:

```ts
import { useHead } from '@unhead/dynamic-import'

// Types for body event handlers
interface BodyEvents {
  // Printing events
  onafterprint?: string | ((el: Element) => void) // After print dialog closes
  onbeforeprint?: string | ((el: Element) => void) // Before print dialog opens

  // Page lifecycle events
  onbeforeunload?: string | ((el: Element) => void) // Before page is unloaded
  onload?: string | ((el: Element) => void) // Page finished loading
  onunload?: string | ((el: Element) => void) // Page is being unloaded

  // Navigation events
  onhashchange?: string | ((el: Element) => void) // URL hash has changed
  onpagehide?: string | ((el: Element) => void) // User navigates away
  onpageshow?: string | ((el: Element) => void) // User navigates to page
  onpopstate?: string | ((el: Element) => void) // Window history changes

  // Connection events
  onoffline?: string | ((el: Element) => void) // Browser goes offline
  ononline?: string | ((el: Element) => void) // Browser goes online

  // Other events
  onerror?: string | ((el: Element) => void) // Error occurs
  onmessage?: string | ((el: Element) => void) // Message is received
  onresize?: string | ((el: Element) => void) // Window is resized
  onstorage?: string | ((el: Element) => void) // Web Storage is updated
}
```

::warning
Remember that these events should generally be used with `{ mode: 'client' }` to ensure they work properly with server-side rendering.
::

## Practical Examples

### How Do I Respond to Window Resize?

Track window size changes and update application state:

```ts
import { useHead } from '@unhead/dynamic-import'

useHead({
  bodyAttrs: {
    onresize: (e) => {
      console.log('Window resized', e)
      // Update responsive state, recalculate layouts, etc.
    }
  }
}, { mode: 'client' })
```

### How Do I Track Page Load Performance?

Measure and report page load performance metrics:

```ts
import { useHead } from '@unhead/dynamic-import'

useHead({
  bodyAttrs: {
    onload: () => {
      // Report page load timing data
      if (window.performance) {
        const perfData = window.performance.timing
        const pageLoadTime = perfData.loadEventEnd - perfData.navigationStart
        console.log(`Page loaded in ${pageLoadTime}ms`)

        // Send to analytics
        if (window.analytics) {
          window.analytics.track('Page Load Time', {
            milliseconds: pageLoadTime
          })
        }
      }
    }
  }
}, { mode: 'client' })
```

### How Do I Handle Offline/Online Status?

Notify users when they lose internet connection:

```ts
import { useHead } from '@unhead/dynamic-import'

useHead({
  bodyAttrs: {
    onoffline: () => {
      // Show offline notification
      showNotification('You are currently offline. Some features may be unavailable.')
    },
    ononline: () => {
      // Show back online notification
      showNotification('You are back online!')
      // Resync data if needed
      syncData()
    }
  }
}, { mode: 'client' })
```

## What Are the Best Practices for DOM Events?

1. **Always use `{ mode: 'client' }`** when working with event handlers to ensure proper hydration
   ```ts
   useHead({
     bodyAttrs: {
       onresize: () => handleResize()
     }
   }, { mode: 'client' }) // Critical for event handlers
   ```

2. **Keep event handlers lightweight** to avoid performance issues
   ```ts
   // Good: Lightweight handler that delegates complex logic
   useHead({
     bodyAttrs: {
       onresize: () => requestAnimationFrame(recalculateLayout)
     }
   }, { mode: 'client' })
   ```

3. **Use `useScript()` for script-related events** rather than direct script event handlers
   ```ts
   // Prefer this approach for scripts
   useScript({
     src: 'https://example.com/analytics.js',
     onLoaded: api => api.initialize()
   })
   ```

4. **Clean up resources** in event handlers to prevent memory leaks
   ```ts
   useHead({
     bodyAttrs: {
       onload: () => {
         const observer = new ResizeObserver(handleResize)
         observer.observe(document.body)

         // Store cleanup function for framework to use
         return () => observer.disconnect()
       }
     }
   }, { mode: 'client' })
   ```

## When Should I Use DOM Events vs useScript?

| Scenario | Recommended Approach |
|----------|---------------------|
| Script loading and interaction | [`useScript()`](/docs/head/api/composables/use-script) |
| Window resize handling | DOM events with `bodyAttrs` |
| Page lifecycle events | DOM events with `bodyAttrs` |
| Print events | DOM events with `bodyAttrs` |
| Stylesheet loading | DOM events with `link` tags |
| Online/offline detection | DOM events with `bodyAttrs` |

## Key Takeaways

::tip
- Use `onload` and `onerror` attributes for script events
- Event handlers work in both SSR and CSR contexts
- Prefer `useScript()` for advanced script event handling
- DOM events are automatically cleaned up on component unmount
::

## See Also

- [Loading Scripts](/docs/head/guides/core-concepts/loading-scripts) - Advanced script loading
- [useScript() API](/docs/head/api/composables/use-script) - Script composable reference
- [useHead() API](/docs/head/api/composables/use-head) - Full API reference