Home/Field Guide/Client extensions & APIs
CONCEPT 15
Custom elements and frontend integration
Mount an interactive widget with a stable HTML contract and scoped behavior.
How it appears on a page
The Custom Element client extension tells Liferay which tag and frontend resources to load. The browser upgrades that tag when its definition is registered. Put app initialization in connectedCallback and tear down listeners or network work in disconnectedCallback. Account for navigation and multiple widget instances. Use a tag name containing a hyphen and guard against duplicate registration.
Define the boundary
Keep presentation separate from record ownership. Pass only documented, safe configuration into the widget. Use a same-origin public API with appropriate authentication or a deliberate external API contract with a restricted CORS policy. Sanitize rendered data, provide loading and error states, and keep the widget usable by keyboard.
Styling can use carefully scoped CSS or Shadow DOM. Shadow DOM reduces style collisions but changes theming and accessibility integration details. Decide which design tokens inherit through the boundary. If configuration demands apply to an entire page or site, review supported global CSS/JS or theme CSS types and their scope before using a widget as a global loader.
Integrate with other experiences
Use a data set for configurable results when supported and choose the suitable frontend data set extension point for cells or filters. Keep labels and formatting separate from machine keys. Test editor and published modes, repeated widgets, small screens, locales, and a user without data access.
Practice
Follow Lab 03 to package a dependency-free custom element, then attach it to a test page. The lab includes exact YAML, source, deployment checks, and common failure symptoms.