UI Components

When building custom areas of the Control Panel, you should aim to use the UI components as much as possible.

These will allow you to write UIs that match the design of Statamic without needing to worry about styles or Tailwind classes. It also allows you to keep your UIs in sync with our design system without having to do any additional work. In short, they’re here to make your life easier.

You can treat these components like an extension of HTML itself. They should just work.

For example, if you need a card, don’t use <div class="bg-white p-4 rounded border shadow-sm">, use the <ui-card> component!

Syntax

All of the components are available with their kebab-cased name prefixed with ui-. For example:

<ui-card>
    <ui-heading text="A lovely card" />
    <ui-button @click="doSomething" text="Click me" />
</ui-card>

This syntax works in Blade and Vue, which is especially handy for those times when you’re bouncing back and forth between them.

Importing

You can optionally import the UI components and namespace them, which gives your IDE the ability to autocomplete, link to the original components, and other useful dev-centric workflows. You import them from @statamic/cms/ui.

<script setup>
import { Card, Heading, Button } from '@statamic/cms/ui';
</script>
<template>
    <Card>
        <Heading text="A lovely card" />
        <Button @click="doSomething" text="Click me" />
    </Card>
</template>

Anatomy of a Component

Most of our components use Reka under the hood, and are built with Vue.js’s composition API.

We utilize Class Variariance Authority to dynamically assemble our classes and styles based on variants and props.

Hot Tip!

These docs are a work in progress during the Alpha. We’re doing some major reorganizing of the docs for the v6 launch and will have complete documentation sometime between now and then. In the meantime, explore the components themselves to see what exists and what props/events are avilable.

Components

Auth Card

TODO

Badge

Highlight contextual information, like status, count, or related data. You can pass text through a text prop or use it like an HTML tag pair.

<ui-badge color="green" size="lg">New</ui-badge>
<ui-badge color="green" size="lg" text="Few" />

Sizes

Badges are available in two sizes via the size prop.

<ui-badge size="sm">Small</ui-badge>
<ui-badge>Default</ui-badge>
<ui-badge size="lg">Large</ui-badge>

Colors

Use the color attribute to change the badge’s color.

<ui-badge>Default</ui-badge>
<ui-badge color="white">White</ui-badge>
<ui-badge color="black">Black</ui-badge>
<ui-badge color="red">Red</ui-badge>
<ui-badge color="orange">Orange</ui-badge>
<ui-badge color="amber">Amber</ui-badge>
<ui-badge color="yellow">Yellow</ui-badge>
<ui-badge color="lime">Lime</ui-badge>
<ui-badge color="green">Green</ui-badge>
<ui-badge color="emerald">Emerald</ui-badge>
<ui-badge color="teal">Teal</ui-badge>
<ui-badge color="cyan">Cyan</ui-badge>
<ui-badge color="sky">Sky</ui-badge>
<ui-badge color="blue">Blue</ui-badge>
<ui-badge color="indigo">Indigo</ui-badge>
<ui-badge color="violet">Violet</ui-badge>
<ui-badge color="purple">Purple</ui-badge>
<ui-badge color="fuchsia">Fuchsia</ui-badge>
<ui-badge color="pink">Pink</ui-badge>
<ui-badge color="rose">Rose</ui-badge>

Variants

Use the variant prop to change the badge’s style and shape. Flat badges are in slightly taller than default ones to account for the optical perception of borders and shadows.

<ui-badge size="lg">Default</ui-badge>
<ui-badge variant="flat" size="lg">Flat</ui-badge>

Sub-Text

Use the sub-text prop to add supporting text, perfect for counts or numbers.

<ui-badge color="black" sub-text="42">Events</ui-badge>
<ui-badge color="purple" sub-text="21">Updates</ui-badge>

Icons

Badges can contain icons through the use of slots or by using the icon prop to pass the name of an icon.

<ui-badge icon="mail">[email protected]</ui-badge>

Pills

Use the pill prop to round out the badge.

<ui-badge pill>Pill</ui-badge>

As a link

Badges can be used as links by passing an href prop.

<ui-badge pill variant="flat" size="lg" href="https://statamic.dev/">
	<p>Go read the <b>docs</b></p>
</ui-badge>

Buttons

TODO

Calendar

TODO

Card

TODO

Character Counter

TODO

Checkbox

TODO

Code Editor

TODO

Combobox

TODO

CommandPalette

TODO

Related to Command Palette stuff here.

Context

TODO

Create Form

TODO

DataTable

TODO

DatePicker

TODO

DateRangePicker

TODO

Description

TODO

Drag Handle

TODO

Dropdowns

TODO

Editable

TODO

Error Message

TODO

Empty State

TODO

Field

TODO

Header

TODO

Heading

TODO

Icon

TODO

Input

TODO

Label

TODO

Listings

You can create a fully fledged listing using the aptly named Listing component with search, filters, column customization, etc.

In most cases, you can use the self-closed component and control the behavior using props.

<script setup>
import { Listing } from '@statamic/cms/ui';
</script>
<template>
    <Listing :items="..." />
</template>

Live Preview

TODO

Modals

TODO

Pagination

TODO

Panels

TODO

Popovers

TODO

Publish Forms

You can create a form using the publish components.

The required components depends on the complexity of what you’re building.

• Very simple forms may not need any Vue or JavaScript at all, and could simply use the PublishForm class directly from your controller.
• If you need JavaScript or Vue, the PublishContainer component can be paired with blueprint data to render an entire form.
• The PublishContainer component can have its contents overridden if you need more control over the layout or behavior of the form.

PublishForm

For very simple forms …

PublishContainer

The PublishContainer component is the workhorse. For a basic form, you can use it self-closed with some props, and it will render exactly what you need.

<script setup>
import { PublishContainer, Button } from '@statamic/cms/ui';
</script>
<template>
    <Button @click="save" text="Save" />
    <PublishContainer
        v-model="values"
        :blueprint="blueprint"
        :meta="meta"
        :errors="errors"
    />
</template>

Based on the provided blueprint, it will render any tabs, sections, and fields appropriately.

You may customize the layout of the form by providing slot content.

<PublishContainer>
    <Tabs /> etc
</PublishContainer>

Save Pipeline

The save pipeline pairs with a PublishContainer to save your data, render validation errors, fire hooks, etc.

The data from your publish container will be sent through the steps. The only required step is the Request.

You provide the pipeline class with a reference to the publish container, the saving state, and errors, and it will update them for you appropriately.

You may provide additional steps, such as the AfterSaveHooks here.

Once everything is done, the then callback will be run, like a promise.

Any errors can be caught in the catch callback. If the pipeline is intentionally stopped, e will be an instance of PipelineStopped.

<script setup>
import { Pipeline, Request, AfterSaveHooks } from '@statamic/cms/save-pipeline';
import { ref, useTemplateRef } from 'vue';

let saving = ref(false);
let errors = ref({});
let container = useTemplateRef('container');

function save() {
    new Pipeline()
        .provide({ container, errors, saving })
        .through([
            new Request(url, method),
            new AfterSaveHooks(name, payload)
        ])
        .then((response) => {
            //
        })
        .catch((e) => {
            //
        });
}
</script>
<template>
    <template v-if="saving">Saving...</template>
    <Button @click="save" text="Save" />
    <PublishContainer ref="container" :errors="errors" />
</template>

Radio

TODO

Select

TODO

Separator

TODO

Skeleton

TODO

Slider

TODO

StatusIndicator

TODO

Subheading

TODO

Switch

TODO

Splitter

TODO

Table

TODO

Tabs

TODO

Textarea

TODO

Time Picker

TODO

Tooltip

TODO

Toggle

TODO

Widget

TODO