UI Components

Discover common components to help build the foundation of your user interface.

Developing a customization requires you to implement a user interface (UI). To facilitate the development of UI features, we provide ready-to-use components based on the commercetools design system, UI Kit. Using these components provides users of your customizations a similar user interface to the Merchant Center's built-in applications. This helps to provide a consistent and familiar experience for your users.

Spacings components

The <Spacings> components let you position elements within your customization. The two primary variants of the <Spacings> components: Stack and Inline.

You can think about these variants in the following way:

  • Stack: stacks elements vertically.
  • Inline: arranges elements horizontally.

The <Spacings> components are implemented using CSS Flexbox. This makes it simple to align children of these elements together and control the spacing between them.

Let's say we are implementing a List Page, which is a page to show a list of a specific resource.

A simple layout might look something like this:

Layout List Page Placeholders

Because most of the elements are vertically stacked, we can use the Stack component.

channels.jsJavaScript React
import Spacings from '@commercetools-uikit/spacings';
const Channels = () => {
// ...
return (
<Spacings.Stack>
<div>Title</div>
<div>Description</div>
<table>{/* Table data */}</table>
<div>{/* Pagination */}</div>
</Spacings.Stack>
);
};

By default, the Stack component has a default scale of s. The scale determines the space between each child.

In our Channels component example, we want to have different amounts of space between individual components. To do this, we can nest multiple Stack components with different scale values.

channels.jsJavaScript React
import Spacings from '@commercetools-uikit/spacings';
const Channels = () => {
// ...
return (
<Spacings.Stack scale="l">
<Spacings.Stack scale="s">
<div>Title</div>
<div>Description</div>
</Spacings.Stack>
<Spacings.Stack scale="xs">
<table>{/* Table data */}</table>
<div>{/* Pagination */}</div>
</Spacings.Stack>
</Spacings.Stack>
);
};

The changes we made can be translated as:

  • The outer elements have a scale of l, which provides a relatively large amount of space in between.
  • The title and description have a scale of s, which makes them relatively close to each other.
  • The table and pagination have a scale of xs, which makes them very close to each other.

Using these principles, you can use as many Stack components as is necessary to define your vertical layout.

The same principles apply to the Inline components.

Typography

To render text within your customization, use the <Text> component. This component uses font styles from the UI Kit design system to ensure consistent typography across the Merchant Center.

The <Text> component exposes the following variants:

  • Headline and Subheadline: for headline elements from H1 to H5.
  • Body: for normal content.
  • Detail: for smaller or secondary content.
  • Caption: for small descriptive labels that provide additional information in a given context.

Let's add these styles to our example Channels component:

channels.jsJavaScript React
import Spacings from '@commercetools-uikit/spacings';
import Text from '@commercetools-uikit/text';
const Channels = () => {
// ...
return (
<Spacings.Stack scale="l">
<Spacings.Stack scale="s">
<Text.Headline as="h2">Title</Text.Headline>
<Text.Body>Description</Text.Body>
</Spacings.Stack>
<Spacings.Stack scale="xs">
<table>{/* Table data */}</table>
<div>{/* Pagination */}</div>
</Spacings.Stack>
</Spacings.Stack>
);
};

Rendering data in tables

A common way to display data is by using tables. To do this, you can use the <DataTable> component inside your customization.

To get started, you need to define the columns of the table.

const columns = [
{ key: 'name', label: 'Channel name' },
{ key: 'key', label: 'Channel key', isSortable: true },
{ key: 'roles', label: 'Roles' },
];

In this example, we define three columns with the key as the identifier, a label, and we make the key column sortable.

Next, we render the table.

channels.jsJavaScript React
import Spacings from '@commercetools-uikit/spacings';
import Text from '@commercetools-uikit/text';
import DataTable from '@commercetools-uikit/data-table';
import { NO_VALUE_FALLBACK } from '@commercetools-frontend/constants';
const columns = [
{ key: 'name', label: 'Channel name' },
{ key: 'key', label: 'Channel key', isSortable: true },
{ key: 'roles', label: 'Roles' },
];
const itemRenderer = (item, column) => {
switch (column.key) {
case 'roles':
return item.roles.join(', ');
case 'name':
const localizedName = item.nameAllLocales.find(
(field) => field.locale === 'en'
);
return localizedName ?? NO_VALUE_FALLBACK;
default:
return item[column.key];
}
};
const Channels = () => {
// ...
return (
<Spacings.Stack scale="l">
<Spacings.Stack scale="s">
<Text.Headline as="h2">Title</Text.Headline>
<Text.Body>Description</Text.Body>
</Spacings.Stack>
<Spacings.Stack scale="xs">
<DataTable
columns={columns}
rows={channels.results}
itemRenderer={itemRenderer}
/>
<div>{/* Pagination */}</div>
</Spacings.Stack>
</Spacings.Stack>
);
};

The itemRenderer is the main function used to render the table cell values. It can be a simple string or some React components.

The rows field is the list of the actual data that needs to be rendered in the table.