Components

Creating UI Components

Semantic UI components are standard Web Components built with an integrated authoring framework that simplifies common UI development tasks like managing state, rendering templates, handling events, and styling.

Getting Started: Before diving into the technical guides, consider the interactive tutorial for a hands-on introduction to Semantic UI features.

The component framework includes:

• Declarative Templating: A reactive AST-based templating system for rendering component views using expressions, conditionals, loops, subtemplates, snippets, and helpers. Integrates with a Signals-based reactivity system for efficient DOM updates and supports component composition similar to other modern frameworks.
• Reactivity System: A performant Signals-based system for managing component state and derived computations, including convenient mutation helpers.
• Scoped Styling: An integrated system using CSS variables and layers, leveraging Shadow DOM encapsulation for reliable styling.
• DOM Querying: A chainable DOM querying library (@semantic-ui/query) specifically designed to work effectively with Shadow DOM boundaries.
• Event Handling: A declarative system for binding event listeners within the component, including support for custom events and event delegation.
• Key Bindings: A declarative format for defining keyboard shortcuts scoped to your component, supporting sequences and combinations.
• Lifecycle Management: Enhanced lifecycle callbacks providing granular control during component initialization, rendering (client and server-side), and destruction.

Minimal Example

The following example demonstrates the basic structure for defining a component using defineComponent.

Developer Experience

Web components can be notoriously difficult to integrate using vanilla js. Semantic UI seeks to improve the experience working with web standards by providing all the modern tooling that developers expect to build things quickly, but without a compilation step or developer magic.

• Reducing boilerplate for common tasks like state management and event handling.
• Providing a consistent API across different features (templating, reactivity, querying).
• Simplifying interaction with the Shadow DOM through the tailored query library.
• Offering declarative approaches for features like key bindings and templating logic.

Components defined using defineComponent can be registered with a tagName for direct use in HTML or exported without a tagName for use as subtemplates within other components.

Framework Integration: As standard Web Components, elements created with Semantic UI can be used directly within applications built with React, Vue, Angular, or any other framework that supports custom elements. They render natively in the browser without requiring framework-specific compilation.

Key Features

Use In Any Framework

Components are defined using defineComponent, which registers a standard custom element (if tagName is provided) usable natively in the browser or within other frameworks.

defineComponent({
  tagName: 'my-component',
  template: '...',
  css: '...',
  defaultState: { ... },
  settings: { ... },
  createComponent: () => ({ ... }),
  onCreated: () => { ... },
  onRendered: () => { ... },
  onDestroyed: () => { ... },
});

Declarative Templating

Components use a built-in templating system that supports expressions, slots, conditionals, snippets, loops, and more for rendering views from component data.

{#each user in users}
  <div class="user">
    {#if user}
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    {else}
      <p>No info provided.</p>
    {/if}
  </div>
{/each}

Integrated Styling

Components utilize an integrated styling system leveraging CSS layers and variables, with style encapsulation provided by the Shadow DOM.

/* expose theming variables for your component
   inherited from design system
*/
:host {
  --counter-padding: var(--padding);
  --counter-value-color: var(--primary-text-color);
}
.counter {
  padding: var(--counter-padding);

  .value {
    color: var(--counter-color);
  }
}

Events

Components include built-in event management using a declarative syntax, simplifying the process of handling user interactions and dispatching custom events.

const createComponent = ({state, dispatchEvent}) => ({
  increment(amount) {

    // update internal counter
    state.counter.increment(amount);

    // dispatches a dom event 'increment' from this web component
    dispatchEvent('increment', {
      counter: state.counter.value,
      amount
    });
  },
  decrement(amount) {
    // update internal counter
    state.counter.decrement(amount);

    // dispatches a dom event 'decrement' from this web component
    dispatchEvent('decrement', {
      counter: state.counter.value,
      amount
    });
  }
});

Listen to internal events and trigger component functionality.

const events = {
  'click .increment': ({ self }) => self.increment(),
  'click .decrement': ({ self }) => self.decrement(),
};

Or listen to external dispatched events from other components.

const events = {
  // listen to the increment, decrement event from another component
  'increment ui-counter, decrement ui-counter': ({ self }) => self.logValue(),
};

Or bind global events tied to your components lifecycle.

// listen to global hashchange, teardown when component is destroyed
const events = {
  'global hashchange window': ({ self }) => self.updateSomething(),
};

Keybindings

Bind key bindings scoped to your component that include key combinations or sequences.

const keys = {
  'up': ({ self }) => self.decrement(),
  'down': ({ self }) => self.increment(),
  'shift + up': ({ self }) => self.decrement(10),
  'shift + down': ({ self }) => self.increment(10),
};