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:
SwitchandSegmentedControlare the kit components behind their existing props (SwitchtakescheckedandonChange).DropdownMenuis the older menu component. The kit’s menu root isDropdownMenuRoot; its parts keep their names (DropdownMenuTrigger,DropdownMenuContent,DropdownMenuItem, …).
Components
| Component | Exports | Notes |
|---|---|---|
| Button | Button | variant: default, secondary, outline, ghost, destructive, link, toolbar. size: sm, default, lg. asChild. type defaults to "button" |
| IconButton | IconButton | icon 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 |
| Switch | Switch | checked, onChange, label |
| Checkbox | Checkbox | Radix checkbox props |
| RadioGroup | RadioGroup, RadioGroupItem | String values |
| Select | Select, SelectTrigger, SelectValue, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton | String values |
| SegmentedControl | SegmentedControl | value, options as [value, label] pairs, onChange |
| TextField, Textarea | TextField, Textarea | Native input props, plus size (sm, default) and invalid |
| Dialog | Dialog, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose, DialogOverlay | |
| Popover | Popover, PopoverTrigger, PopoverAnchor, PopoverContent, PopoverArrow | |
| DropdownMenu | DropdownMenuRoot, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | |
| Tooltip | Tooltip, TooltipTrigger, TooltipContent | |
| Tabs | Tabs, TabsList, TabsTrigger, TabsContent | String 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.
| Component | Props | Does |
|---|---|---|
SettingsPage | title, description?, icon? | Page header and body |
SettingsSection | title?, aside?, note?, danger?, bare? | A titled group of rows; bare drops the card |
SettingsCard | danger? | A card without a title |
SettingsRow | label, description?, disabled?, children | A label on the left, a control on the right |
SettingsField | label, htmlFor?, children | A stacked label and field |
SettingsNote | children | Small explanatory text |
SettingsSwitch | checked, onChange, disabled?, label? | A switch not tied to config |
ConfigSwitchRow | keyPath, label, description?, invert?, disabled?, onChange? | A row with a switch bound to AppEnv.config at keyPath |
ConfigSelectRow | keyPath, label, description?, options?, disabled?, onChange? | A select bound to config; options default to the schema’s enum |
ConfigSegmentedRow | keyPath, label, description?, options?, disabled? | The same as a segmented control |
StatusPill, NeedsServerPill | kind: ok, warn, bad, off, server | Status badges |
PrivacyNote | kind?: local, network, warn | Says where data goes |
ProviderCard, ProviderLogo | The 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:
| Component | Use |
|---|---|
RetinaImg | Images from static/images/ or airpost-asset:// URLs, at 2x; mode={RetinaImg.Mode.ContentIsMask} tints by text colour |
Flexbox | A flex container: direction (row or column), inline, height |
ScrollRegion | The app’s scroll container with its scrollbar |
Spinner | Loading spinner (visible) |
InjectedComponent, InjectedComponentSet | Render whatever is registered for a descriptor, so your plugin can offer its own slots |
KeyCommandsRegion, BindGlobalCommands | Bind keymap commands to a region or the window |
Menu, ButtonDropdown, DropdownMenu, MultiselectDropdown | Older menu components |
FixedPopover, DatePickerPopover, Modal | Used with Actions.openPopover and Actions.openModal |
ParticipantsTextField, TokenizingTextField | Contact token fields |
DateInput, DatePicker, TimePicker, MiniMonthView | Date and time input |
Table, SelectableTable, EditableTable, EditableList | Tables and editable lists |
MailLabel, MailLabelSet, MailImportantIcon, AccountColorBar | Mail decorations |
ContactProfilePhoto, AttachmentItem | Contact photos, attachment tiles |
ComposerEditor, ComposerSupport | The composer’s editor and its helpers |
ListensToFluxStore, ListensToObservable, ListensToMovementKeys, HasTutorialTip, CreateButtonGroup | Higher-order components |
CodeSnippet, CopyButton, EmptyListState, SyncingListState, Notification | Small pieces |
Webview | Deprecated 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 carriesdir="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.