Lifecycle Events An overview of component lifecycle refresh-cw Guide

Lifecycle Events

Each web component has lifecycle callbacks that help you define behavior at each point in the loading, rendering, and removal process.

Semantic UI components wrap native web components but provide additional callbacks that give you more granular control over how the component is defined.

  • createComponent - Defines your component instance that includes the invokable functionality of your component and exposed variables.
  • onCreated - Callback after your component instance is initialized but before it is attached to the DOM
  • onRendered - Callback after your component is rendered to the DOM
  • onDestroyed - Callback after your component is removed from the DOM
  • onThemeChanged - Callback when your components theme is updated

For a more detailed description of how callbacks are fired refer to the callback event sequence diagram.

Render Function Unlike many front end frameworks which require your render function to return the html for your component, your component’s html is defined in the template passed to defineComponent.

Lifecycle Callbacks

createComponent

createComponent is used to defined the component instance at runtime. Each web component will have its own instance which will include its own state and settings.

For more information see the dedicated section for component instances.

Initialize

If you include a method called initialize in your returned instance it will be called immediately allowing you to set up initial state for the component, for instance adding any reactive calcuations or dynamically defined variables.

onCreated

onCreated fires after the instance is defined but before the DOM is rendered. You can use this callback to handle special behaviors that require the component instance but not its rendered DOM, for instance attaching external event handlers to the page.

onRendered

The onRendered callback occurs after the initial render of the web components Shadow DOM.

This can be used to run code which requires access to the DOM. Although this callback will fire on the server you will not be able to access deeply nested DOM as server rendered components are rendered in isolation.

onDestroyed

The onDestroyed callback is called after the component is removed from the page.

onThemeChanged

The onThemeChanged callback is a special callback that fires when a user swaps themes. This can be used to modify the component based on whether the user prefers light or dark mode.

Server Side Rendering

Hydration

The default rendering engine for Semantic UI components is lit this means you can use any existing Lit SSR package to render components on the server.

UI Components - All UI framework components in Semantic UI are designed to work with server side hydration out of the box.

Lifecycle Events on Server

All lifecycle events will fire on the server in the same order as on the client.

This means you should use isServer or isClient during server side rendering to handle checking for globals that may not be defined.

const onRendered = function ({ isClient, self }) {
if(isClient) {
self.url.set(window.location.pathname);
}
};

Callback Arguments

Using Callback Arguments

Each callback receives a destructurable set of arguments that can be used to interact with the internals of the component. This allows you to pull into any function scope necessary values without managing imports or the this context.

These are accessible from all lifecycle callbacks, as well as inside event listeners and keybindings.

const onCreated = ({isServer, darkMode, self}) {
if(!isServer && isDarkMode) {
self.setDarkMode();
}
};

You can use these to do things like query the DOM, setting up custom reactivity and much more.

Standard Arguments

The following parameters are destructurable from all callbacks.

For information on self aliases see self aliases.

parameteruse
elthe DOM element of the web component
selfthe template instance from createComponent
tplalias for self
componentalias for self
$allows you to query the shadow dom of the component
$$allows querying deep nested content including slots
reactiona reactive context for computations
reactiveVara function to define a reactive variable
flusha function to immediately trigger queued reactions
afterFlusha callback after reactive computations are flushed
settingsa read-write copy of the component’s settings
statea reactive data store for internal state
datathe full data context used when evaluated expressions
isRendereda function returning whether the DOM has rendered
isServerwhether component is rendering on server
isClientwhether component is rendering on client
dispatchEventhelper to emit events from the component
attachEventhelper to listen to external events
bindKeyhelper to bind keyboard shortcuts dynamically
abortControllerabortSignal for async events tied to lifecycle
templatethe underlying semantic template
templateNamethe name of the current semantic template
templatesall rendered templates on current page
findTemplatehelper to find a specific template
findParenthelper to find a specific parent template
findChildhelper to find a child template
findChildrenhelper to find multiple child templates
darkModeboolean for if dark mode is active

Event Callbacks

Event handlers also have access to a few additional arguments

parameteruse
elthe dom element that fired the event
eventthe event object
valueevent.target.value from target element
dataevent.detail + data attributes on dom element

Key Bindings

Key bindings also have access to a few additional arguments

parameteruse
inputFocusedwhether any input/contenteditable is focused
repeatedKeywhether the key is held down

Lifecycle events provide two helpers isClient and iServer which can be used to handle

DOM Lifecycle Events

Each component will also emit a DOM event when a lifecycle event fires. This can be useful to respond to the render cycle of subcomponents from elsewhere in the page

eventwhen fired
createdCallback after your component instance is initialized but before it is attached to the DOM
onRenderedCallback after your component is rendered to the DOM
onDestroyedCallback after your component is removed from the DOM

These can be listened to from other components in the same way as other DOM or custom events.

For more information on custom events see the dedicated subsection

Callback Sequence

The following diagram shows the sequence of events that occur when a component is rendered to the page.

Component Lifecycle