Build a theme section

Open the theme code editorCopy Anchor Link

In the admin, open Online store → Themes and choose Edit in code editor on the theme you want to change. The Customizer's top bar links to the editor too.

The editor works on the theme's draft. Saving never changes the live storefront. Publishing is a separate step at the end.

Create the section fileCopy Anchor Link

Open the command palette (Cmd+Shift+P on a Mac, Ctrl+Shift+P elsewhere) and run Theme: New Section…. Name it usp-strip. The editor writes src/sections/usp-strip.tsx with a working starter: a heading, a text, a slot for child blocks and the standard style list.

There is no registry to update. The theme compiler finds every defineSection in src/sections/ on save.

Write the sectionCopy Anchor Link

Replace the file's content with this:

import { EditableText, defineSection, field } from '@poltura/theme-sdk/elements';
import { cn } from '@poltura/theme-sdk/ui';

export const uspStrip = defineSection({
  type: 'usp-strip',
  label: 'USP strip',
  description: 'One short line of reassurance',
  icon: 'section',
  category: 'marketing',
  settings: {
    text: field.text({ label: 'Text', default: 'Free delivery over 50' }),
    alignment: field.select({
      label: 'Alignment',
      options: [
        { value: 'left', label: 'Left' },
        { value: 'center', label: 'Center' },
      ],
      default: 'center',
    }),
  },
  style: ['spacing', 'background', 'typography', 'visibility'],
  component: ({ settings, attrs }) => (
    <section {...attrs} className={cn(attrs.className, 'py-6')}>
      <div className='theme-container'>
        <EditableText
          setting='text'
          as='p'
          className={cn('text-foreground', settings.alignment === 'center' && 'text-center')}
        />
      </div>
    </section>
  ),
});

What each part does:

• type is the section's permanent key in the theme's page files. Keep it once merchants use the section. To rename it later, list the old key in renamedFrom.
• label, description, icon and category are what merchants see in the Customizer's section picker. marketing lists it under Marketing.
• settings become the fields of the section's inspector. Each field.* builder has a label and a default, and the component receives the values already typed as settings.
• style lists the style controls merchants get. The platform turns their choices into classes and attributes on attrs.
• attrs must be spread onto exactly one root element, with cn(attrs.className, ...) to merge your own classes. Without it, the style controls do nothing.
• EditableText renders the text setting and lets merchants edit it in place on the canvas.

Every field and style control is listed in Sections, blocks and element styles.

Save and read the checkCopy Anchor Link

Save the file. The editor runs the theme check on every save and lists anything wrong in the Problems panel, with the line and column. The section above passes. These are the mistakes it catches most often, with the message you get (the last one is shortened):

src/sections/usp-strip.tsx(26,19): [usage] reads setting "txt" no element definition declares for usp-strip (declared: text, alignment)
src/sections/usp-strip.tsx(18,7): [types] Type '"middle"' is not assignable to type '"center" | "left" | undefined'.
src/sections/usp-strip.tsx(5,3): [elements] type "UspStrip" must be kebab-case starting with a letter (bad-definition)
src/sections/usp-strip.tsx(2,21): [import] Theme file src/sections/usp-strip.tsx imports "lodash", which is outside the theme surface.

The full import message lists what a theme may import: @poltura/theme-sdk/*, the theme's own files, React, and a fixed set of libraries such as @radix-ui/*, lucide-react, motion and clsx.

Fix them until the panel is empty.

Place it in the CustomizerCopy Anchor Link

In the admin, choose Customize on the theme. On the home page choose Add section, find USP strip under Marketing and add it. You see:

• "Free delivery over 50" on the canvas. Click it and type to change it.
• Alignment with Left and Center in the section's settings.
• Spacing, Background, Typography and Visibility in its style controls.

The Customizer writes the placement into the draft's pages/home.json. Your section's code stays in src/sections/usp-strip.tsx.

PublishCopy Anchor Link

Choose Publish in the Customizer (or Publish in the code editor's status bar). The draft's code and layout go live together. Until then, shoppers see the previous version.