@shopify/ui-extensions

What is @shopify/ui-extensions?

@shopify/ui-extensions is a package that allows developers to create custom UI extensions for Shopify. These extensions can be used to enhance the functionality and appearance of Shopify stores by adding custom components and features.

What are @shopify/ui-extensions's main functionalities?

Custom UI Components

This feature allows developers to create custom UI components like buttons, forms, and more. The code sample demonstrates how to create a simple button that logs a message when pressed.

import { extend, Button } from '@shopify/ui-extensions';

extend('Playground', (root) => {
  const button = root.createComponent(Button, {
    onPress: () => console.log('Button pressed!')
  }, 'Click me');

  root.appendChild(button);
});

Event Handling

This feature allows developers to handle events such as user input. The code sample demonstrates how to create a text field that logs the entered text whenever it changes.

import { extend, TextField } from '@shopify/ui-extensions';

extend('Playground', (root) => {
  const textField = root.createComponent(TextField, {
    label: 'Enter text',
    onChange: (value) => console.log('Text changed:', value)
  });

  root.appendChild(textField);
});

Styling Components

This feature allows developers to style their custom components. The code sample demonstrates how to create a styled view with padding and background color.

import { extend, View, Text } from '@shopify/ui-extensions';

extend('Playground', (root) => {
  const view = root.createComponent(View, {
    style: {
      padding: '10px',
      backgroundColor: 'lightblue'
    }
  },
  root.createComponent(Text, {}, 'Styled View'));

  root.appendChild(view);
});

Other packages similar to @shopify/ui-extensions

react

React is a popular JavaScript library for building user interfaces. It allows developers to create reusable UI components and manage the state of their applications. Compared to @shopify/ui-extensions, React is more general-purpose and can be used for a wide range of web applications, not just Shopify stores.

vue

Vue.js is a progressive JavaScript framework for building user interfaces. It is designed to be incrementally adoptable and can be used to create complex single-page applications. Like React, Vue.js is more general-purpose compared to @shopify/ui-extensions and can be used for various types of web applications.

angular

Angular is a platform and framework for building single-page client applications using HTML and TypeScript. It provides a comprehensive solution for building dynamic web applications. Compared to @shopify/ui-extensions, Angular is a full-fledged framework that offers more built-in features and is suitable for larger applications.

README

@shopify/ui-extensions

This package contains the public type definitions and utilities needed to create a Shopify UI extension. This is a generalized package that is intended to be the long-term home of the surface-specific packages in this repository, like @shopify/checkout-ui-extensions and @shopify/admin-ui-extensions.

Currently, this package contains the API for two surfaces:

• admin
• checkout

This surface-based grouping is mostly cosmetic; all extensions use the same underlying technology, and most of the same “core” components (e.g., Layout, BlockStack, etc) and capabilities (e.g., direct API access, session tokens). Separating APIs by surface makes it easier for a developer to see what is available to them in each context, and gives us a flexible system for introducing components and APIs available in only some surfaces.

An admin extension using “vanilla” JavaScript would be written as follows:

import {
  extension,
  TextField,
  EditorSettings,
} from '@shopify/ui-extensions/admin';

export default extension(
  'Admin::CheckoutEditor::RenderSettings',
  (root, {settings, applySettingChange}) => {
    const editorSettings = root.createComponent(EditorSettings);

    const textfield = root.createComponent(TextField, {
      label: 'Message',
      helpText: 'The message to show to buyers when this extension is rendered',
      value: settings.current.message,
      onChange(value) {
        applySettingsChange({key: 'message', value});
      },
    });

    editorSettings.appendChild(textfield);
    root.appendChild(editorSettings);
  },
);

What is a “UI Extension”?

A UI extension is a JavaScript-based module that can hook in to client-side behaviors on any of Shopify’s first party UI surface areas. No matter whether the developer is embedding into the admin or checkout, whether they are rendering UI or registering listeners for client-side events; it’s all a UI extension.

The most minimal definition of a UI extension has the following properties:

• A name that is presented to merchants when interacting with the extension.
• The extension points that the UI extension implements. These are represented with string identifiers that describe the surface and responsibility of the extension. For example, Checkout::CartLines::RenderAfter gives the UI Extension the ability to render UI after the cart lines in a checkout; WebPixel::Register registers a Web Pixel to track client-side events. A UI Extension can register to support multiple extension points, and must map each to a JavaScript module in their application.

The types in this package allow us to represent additional details about the extension points developers can implement. Each extension point can define what APIs it supports, including:

• What UI Components are available to be rendered, and what properties those UI components accept
• What imperative APIs are provided by the host, for reading and writing data relevant to the extension

The available components and APIs can be different for each extension point. Additionally, Shopify can vary the components and APIs it provides based on many other factors at runtime, like:

• Whether an extension is built by Shopify or a third party
• Whether the API client that owns the extension has certain approval scopes,
• Whether the shop or API client has particular beta flags enabled