DOM Events
DOM event handling is the ability to use raw DOM event listeners in your tags.
This is useful for running logic when certain events happen.
onload
The onload event is special in that providing it will always change the logic src is applied to the tag, to ensure
the tag is always fired.
This is useful for knowing when a script is finished loading.
However, if you're SSR this tag, then this event will likely fire before hydration can occur to attach the listener.
To get around this you should ensure these entries are client only.
useHead({
script: [
{
src: 'https://example.com/analytics.js',
// this will always run
onload: (el) => {
console.log('loaded', el)
}
}
]
}, { mode: 'client' })
And that's it, Unhead will manage all side effects for you.
HTTP Events
These are only supported for <script> and <link> tags.
export interface HttpEventAttributes {
/**
* Script to be run on abort
*/
onabort?: string | ((el: Element) => void)
/**
* Script to be run when an error occurs when the file is being loaded
*/
onerror?: string | ((el: Element) => void)
/**
* Script to be run when the file is loaded
*/
onload?: string | ((el: Element) => void)
/**
* The progress event is fired periodically when a request receives more data.
*/
onprogress?: string | ((el: Element) => void)
/**
* Script to be run just as the file begins to load before anything is actually loaded
*/
onloadstart?: string | ((el: Element) => void)
}
Body Events
These are only supported with bodyAttr.
Note that the HTML spec allows body events, they will be proxied to the window object
for better browser support.
export interface BodyEvents {
/**
* Script to be run after the document is printed
*/
onafterprint?: string | ((el: Element) => void)
/**
* Script to be run before the document is printed
*/
onbeforeprint?: string | ((el: Element) => void)
/**
* Script to be run when the document is about to be unloaded
*/
onbeforeunload?: string | ((el: Element) => void)
/**
* Script to be run when an error occurs
*/
onerror?: string | ((el: Element) => void)
/**
* Script to be run when there has been changes to the anchor part of the a URL
*/
onhashchange?: string | ((el: Element) => void)
/**
* Fires after the page is finished loading
*/
onload?: string | ((el: Element) => void)
/**
* Script to be run when the message is triggered
*/
onmessage?: string | ((el: Element) => void)
/**
* Script to be run when the browser starts to work offline
*/
onoffline?: string | ((el: Element) => void)
/**
* Script to be run when the browser starts to work online
*/
ononline?: string | ((el: Element) => void)
/**
* Script to be run when a user navigates away from a page
*/
onpagehide?: string | ((el: Element) => void)
/**
* Script to be run when a user navigates to a page
*/
onpageshow?: string | ((el: Element) => void)
/**
* Script to be run when the window's history changes
*/
onpopstate?: string | ((el: Element) => void)
/**
* Fires when the browser window is resized
*/
onresize?: string | ((el: Element) => void)
/**
* Script to be run when a Web Storage area is updated
*/
onstorage?: string | ((el: Element) => void)
/**
* Fires once a page has unloaded (or the browser window has been closed)
*/
onunload?: string | ((el: Element) => void)
}
Examples
Window resize
useHead({
bodyAttrs: {
onresize: (e) => {
console.log('resized', e)
}
}
})