Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Developer Toolkit is a curated library of ready-to-use UI building blocks for Shopify app developers. Instead of searching through documentation or starting components from scratch, you browse a catalog of components, templates, and integration patterns — each with working code examples you can copy directly into your project. Every item is built for Shopify’s Polaris design system, so what you copy fits natively into your app’s existing UI.

​
What the toolkit contains

The library is organized into three categories. Each category addresses a different stage of building your app’s UI.

Components

Individual Polaris UI elements: data tables, form fields, badges, banners, navigation items, and more. Use these to build screens that feel native to Shopify.

Templates

Full-page layouts for common app screens: settings pages, onboarding flows, billing upgrade prompts, and empty states. Start with a template instead of composing everything from individual components.

Integrations

Pre-built patterns for connecting your app to third-party services or Shopify APIs. These cover common integration shapes — webhooks, metafields, billing hooks — so you have a proven starting point.

​
Browsing the toolkit

Navigate to Developer Toolkit in the Meridian sidebar. The main view lists all available entries. Use the category filter to narrow the list to Components, Templates, or Integrations. Each entry in the list shows:
  • Name — the display name of the component, template, or integration.
  • Category — which of the three categories it belongs to (components, templates, or integrations).
  • Description — a short explanation of what it does and when to use it.
  • Use cases — a list of specific scenarios where the item is a good fit.
  • Code examples — working code in both JSX and HTML variants.

​
Understanding use cases

Every toolkit entry includes a useCases list. Each use case has a title and a description that explains the specific context where the component or template fits well. Use cases help you answer: “Is this the right component for my situation?” Read through them before you copy the code, especially for components that have similar-looking alternatives. Example use cases for a data table component:
  • Order history list — display a paginated list of merchant orders with sortable columns.
  • App settings audit — show a read-only log of configuration changes with timestamps.
  • Customer segment view — list CRM contacts with filtering by subscription status.
If none of the use cases match your situation, look for a different component or template in the same category.

​
Copying code examples

When you open a toolkit entry, the code viewer shows both a JSX and an HTML version of the example. Switch between them using the tabs at the top of the code panel.
Use the JSX variant when you’re building with React. The examples use Shopify Polaris web components as JSX elements. Copy the snippet into your component file and adjust props as needed.
import React from 'react';

export function StatusBadge({ status }) {
  return (
    <s-badge tone={status === 'active' ? 'success' : 'neutral'}>
      {status}
    </s-badge>
  );
}
Both code variants use Shopify Polaris web components (e.g. <s-box>, <s-text>, <s-badge>). These are the same components used throughout the Meridian UI, so they’ll look and behave consistently across your app.

​
Working with Polaris web components

The Developer Toolkit is built on the Shopify Polaris web component library. Here are practical guidelines for using Polaris components effectively in your Shopify app.

​
Use Polaris attributes, not CSS classes

Polaris web components expose layout and spacing through their own attributes (padding, gap, direction). Do not apply Tailwind or custom CSS classes to Polaris elements — use the component’s built-in attributes instead. 
// Correct: use Polaris attributes
<s-stack direction="inline" gap="base" alignItems="center">
  <s-text type="strong">Plan name</s-text>
  <s-badge tone="success">Active</s-badge>
</s-stack>

// Avoid: applying Tailwind classes to Polaris components
<s-stack className="flex items-center gap-2">
  ...
</s-stack>

​
Use Polaris design tokens for custom elements

When you need to style raw HTML elements alongside Polaris components, reference Polaris design tokens via CSS custom properties. In Tailwind projects, use arbitrary value syntax to preserve theming. 
// Reference a Polaris spacing token in a plain div
<div className="p-[var(--p-space-400)]">
  Custom content alongside Polaris components
</div>

​
Compose screens from toolkit templates first

Before building a new app screen from scratch, check whether a Template entry covers your use case. Templates compose multiple Polaris components into a complete layout with correct spacing and hierarchy. Starting from a template is faster and produces more consistent results than assembling components individually.

​
Check the Shopify Polaris documentation for component attributes

Toolkit examples show common props and attributes, but each Polaris web component has additional options. Before shipping a component, look up its full attribute list in the Shopify Polaris documentation to make sure you’re using the right configuration for your use case.

​
Toolkit entry data model

For reference, here is the structure of a toolkit entry. Understanding this helps if you’re building tooling that reads from the toolkit or integrating the patterns into a design system.
FieldTypeDescription
idstringUnique identifier for the entry.
namestringDisplay name shown in the library.
category"components" | "templates" | "integrations"Which section of the toolkit this entry belongs to.
descriptionstringShort summary of what the entry does.
useCasesComponentUseCase[]List of specific scenarios where the entry applies. Each has a title and description.
examplesComponentExample[]List of named code examples. Each has a name and a code object with jsx and html string variants.
Last modified on May 5, 2026