Framework Integration Integrating Semantic UI into Your Design System code Guide

Framework Integration

Semantic UI components are web components so they can be used directly in many front end frameworks directly.

Using UI Components

Direct Usage - For smaller projects you may consider using UI components directly in app layouts. This is the simplest set up and means you can work one to one with the Semantic UI docs when working on your site.

Custom Framework - For larger projects you may consider wrapping UI components into a design framework. This would mean using the web components as primitives to build additional framework specific integrations for your project. This may include business logic or other project specific requirements that may not be addressed directly in a generalized UI framework.

Using Directly

If you want to use Semantic UI directly in your page without wrapping the components into a custom design framework, you can simply import each component.

Components emit standard DOM events which you can bind event handlers.

In React, you can use web components directly since version 19.

import React from 'react';
import '@semantic-ui/core/components/button';
import '@semantic-ui/core/components/icon';
import '@semantic-ui/core/themes/button.css';
import '@semantic-ui/core/themes/icon.css';
function MyComponent() {
return (
<div>
<ui-button primary>Click me</ui-button>
<ui-icon icon="close"></ui-icon>
</div>
);
}

Integrating into Design Framework

It may often make sense to wrap web components in native wrappers for your framework so that you can simplify passing data and events.

You may also use this to set defaults for your components, or to add additional logic or settings.

React 19 or Newer

React 19 introduced native support for web components, you can directly use the web components without the need for a wrapper component.

import React from 'react';
import '@semantic-ui/core/components/button';
import '@semantic-ui/core/components/icon';
import '@semantic-ui/core/themes/button.css';
import '@semantic-ui/core/themes/icon.css';
export const UIButton = React.forwardRef((props, ref) => <ui-button ref={ref} {...props} />);
export const UIIcon = React.forwardRef((props, ref) => <ui-icon ref={ref} {...props} />);

Legacy React

In React, you can create a generic wrapper component that handles passing properties and event bindings to the underlying web component. This approach is useful if you have multiple web components to wrap.

import React from 'react';
import '@semantic-ui/core/components/button';
import '@semantic-ui/core/components/icon';
import '@semantic-ui/core/themes/button.css';
import '@semantic-ui/core/themes/icon.css';
const WebComponentWrapper = React.forwardRef(({ component, ...props }, ref) => {
const Component = component;
const handleEvent = (event) => {
const eventName = event.type;
const eventHandler = props[eventName];
if (eventHandler) {
eventHandler(event.detail);
}
};
return <Component ref={ref} {...props} onEvent={handleEvent} />;
});
export const UIButton = (props) => <WebComponentWrapper component="ui-button" {...props} />;
export const UIIcon = (props) => <WebComponentWrapper component="ui-icon" {...props} />;

By creating wrapper components or directly using the web components in your design framework, you can provide a consistent and framework-specific way for consumers to use the Semantic UI Web Components in their applications.

Remember to import the necessary CSS files for each component you use, as shown in the examples above.

When deciding whether to create wrapper components or use the web components directly, consider the following:

  • If your framework has native support for web components (e.g., React 19+), you can directly use the web components without the need for wrapper components.
  • If you need to customize the behavior or styling of the web components extensively, creating wrapper components allows you to encapsulate those customizations.
  • If you have a large number of web components to include in your design framework, creating a generic wrapper component (as shown in the React example) can reduce code duplication.

Ultimately, the approach you choose depends on your specific requirements and the conventions of your framework and design system.