Airpost
Plugins

UI kit

The desktop's component kit: buttons, form controls, dialogs, popovers, menus, tooltips and tabs that follow the active theme.

The UI kit is a set of React components built on Radix primitives, with shadcn-like props and markup, styled with plain CSS that reads the theme tokens. Using it means your plugin’s controls match the app and every theme without extra CSS. The source is apps/desktop/src/components/kit/, the styles apps/desktop/static/styles/kit/.

Importing

The kit components are exported flat from mailspring-component-kit:

import { Button, IconButton, Dialog, DialogContent, DialogTitle } from 'mailspring-component-kit';

Two names already existed in the v1 API, so they differ from shadcn:

  • Switch and SegmentedControl are the kit components behind their existing props (Switch takes checked and onChange).
  • DropdownMenu is the older menu component. The kit’s menu root is DropdownMenuRoot; its parts keep their names (DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, …).

Components

ComponentExportsNotes
ButtonButtonvariant: default, secondary, outline, ghost, destructive, link, toolbar. size: sm, default, lg. asChild. type defaults to "button"
IconButtonIconButtonicon or iconUrl, and a required label (the aria-label, and the tooltip unless tooltip={false}). pressed makes it a toggle. variant: ghost (default), outline, secondary, toolbar
SwitchSwitchchecked, onChange, label
CheckboxCheckboxRadix checkbox props
RadioGroupRadioGroup, RadioGroupItemString values
SelectSelect, SelectTrigger, SelectValue, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButtonString values
SegmentedControlSegmentedControlvalue, options as [value, label] pairs, onChange
TextField, TextareaTextField, TextareaNative input props, plus size (sm, default) and invalid
DialogDialog, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose, DialogOverlay
PopoverPopover, PopoverTrigger, PopoverAnchor, PopoverContent, PopoverArrow
DropdownMenuDropdownMenuRoot, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent
TooltipTooltip, TooltipTrigger, TooltipContent
TabsTabs, TabsList, TabsTrigger, TabsContentString values

Every component forwards its ref, passes className and style through, and spreads other props onto its DOM element.

Example

import React from 'react';
import {
  Button,
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose,
} from 'mailspring-component-kit';

export function ConfirmDialog({ open, onOpenChange, onConfirm }) {
  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Delete template?</DialogTitle>
          <DialogDescription>This can't be undone.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="outline">Cancel</Button>
          </DialogClose>
          <Button variant="destructive" onClick={onConfirm}>Delete</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Settings pages

apps/desktop/src/components/settings.tsx has the building blocks every Preferences tab uses. They are exported from mailspring-component-kit.

ComponentPropsDoes
SettingsPagetitle, description?, icon?Page header and body
SettingsSectiontitle?, aside?, note?, danger?, bare?A titled group of rows; bare drops the card
SettingsCarddanger?A card without a title
SettingsRowlabel, description?, disabled?, childrenA label on the left, a control on the right
SettingsFieldlabel, htmlFor?, childrenA stacked label and field
SettingsNotechildrenSmall explanatory text
SettingsSwitchchecked, onChange, disabled?, label?A switch not tied to config
ConfigSwitchRowkeyPath, label, description?, invert?, disabled?, onChange?A row with a switch bound to AppEnv.config at keyPath
ConfigSelectRowkeyPath, label, description?, options?, disabled?, onChange?A select bound to config; options default to the schema’s enum
ConfigSegmentedRowkeyPath, label, description?, options?, disabled?The same as a segmented control
StatusPill, NeedsServerPillkind: ok, warn, bad, off, serverStatus badges
PrivacyNotekind?: local, network, warnSays where data goes
ProviderCard, ProviderLogoThe cards on the integrations pages
import React from 'react';
import {
  SettingsPage,
  SettingsSection,
  SettingsRow,
  ConfigSwitchRow,
  ConfigSelectRow,
  Button,
} from 'mailspring-component-kit';

export default function MyPluginPreferences() {
  return (
    <SettingsPage title="My Plugin" description="What the plugin does.">
      <SettingsSection title="Behaviour">
        <ConfigSwitchRow keyPath="my-plugin.enabled" label="Turn it on" />
        <ConfigSelectRow
          keyPath="my-plugin.mode"
          label="Mode"
          options={[['fast', 'Fast'], ['careful', 'Careful']]}
        />
      </SettingsSection>
      <SettingsSection title="Data" danger>
        <SettingsRow label="Forget everything" description="Clears this plugin's metadata.">
          <Button variant="destructive" onClick={() => {}}>Clear</Button>
        </SettingsRow>
      </SettingsSection>
    </SettingsPage>
  );
}

Other components

mailspring-component-kit also exports the app’s older components, which bundled plugins still use. The list is apps/desktop/src/packages/api/mailspring-component-kit.js; the most useful:

ComponentUse
RetinaImgImages from static/images/ or airpost-asset:// URLs, at 2x; mode={RetinaImg.Mode.ContentIsMask} tints by text colour
FlexboxA flex container: direction (row or column), inline, height
ScrollRegionThe app’s scroll container with its scrollbar
SpinnerLoading spinner (visible)
InjectedComponent, InjectedComponentSetRender whatever is registered for a descriptor, so your plugin can offer its own slots
KeyCommandsRegion, BindGlobalCommandsBind keymap commands to a region or the window
Menu, ButtonDropdown, DropdownMenu, MultiselectDropdownOlder menu components
FixedPopover, DatePickerPopover, ModalUsed with Actions.openPopover and Actions.openModal
ParticipantsTextField, TokenizingTextFieldContact token fields
DateInput, DatePicker, TimePicker, MiniMonthViewDate and time input
Table, SelectableTable, EditableTable, EditableListTables and editable lists
MailLabel, MailLabelSet, MailImportantIcon, AccountColorBarMail decorations
ContactProfilePhoto, AttachmentItemContact photos, attachment tiles
ComposerEditor, ComposerSupportThe composer’s editor and its helpers
ListensToFluxStore, ListensToObservable, ListensToMovementKeys, HasTutorialTip, CreateButtonGroupHigher-order components
CodeSnippet, CopyButton, EmptyListState, SyncingListState, NotificationSmall pieces
WebviewDeprecated since 1.35.0; renders nothing

Prefer the kit components above for new UI; the older ones carry legacy class names that theme CSS may target.

Behaviour

  • Dialogs, popovers, menus, selects and tooltips render into one portal container per window (#ui-portal-root, the last child of <body>), which carries dir="rtl" in right-to-left languages.
  • Escape closes the topmost open layer only.
  • The kit’s CSS uses logical properties (margin-inline-start, padding-inline), so it works in right-to-left layouts without changes.

Styling

Kit elements carry data-slot and state attributes, so you can target them precisely:

[data-slot='button'][data-variant='outline'] { /* ... */ }
[data-slot='switch'][data-state='checked'] { /* ... */ }

Colours, radii, fonts and spacing come from the theme tokens, and paddings scale with --density. Plugin and theme styles load after the kit’s, so on equal specificity your rules win.

For compatibility with Mailspring themes, kit components also render the legacy classes (btn, btn-emphasis, btn-toolbar, btn-icon, slide-switch, …). Those classes are dropped at plugin API 2.0, so don’t write new CSS against them.