Skip to main content

​
Installation

Components are included with the main package: 
import {
  button,
  card,
  badge,
  alert,
  input,
  select,
  table,
  avatar,
  modal,
} from '@frontmcp/ui';

​
Available Components

Button

Versatile buttons with variants, sizes, loading states, and HTMX support

Card

Content containers with headers, footers, and multiple styles

Badge

Status indicators, labels, and dot notifications

Alert

Info, success, warning, and error messages with dismiss support

Form

Inputs, selects, textareas, checkboxes, and form layouts

Table

Data tables with headers, rows, and styling options

List

Description lists and action lists for structured content

Avatar

User avatars with images, initials, and status indicators

Modal

Dialogs and drawers for overlay content

Resource Widgets

App SDK-ready cards, lists, previews, and media helpers built on top of the component primitives.

​
Usage Pattern

All components follow the same pattern: 
import { componentName } from '@frontmcp/ui';

// Basic usage
const html = componentName('content');

// With options
const html = componentName('content', {
  variant: 'primary',
  size: 'md',
  className: 'custom-class',
});

​
Validation

Components validate their inputs using Zod schemas. Invalid options render a styled error box instead of crashing: 
// This renders an error box, not a broken component
const html = button('Click', { variant: 'invalid-variant' });
The error box displays:
  • Component name
  • Invalid parameter
  • Human-readable error message
Error boxes are for development debugging. In production, ensure you pass valid options to avoid displaying error messages to users.

​
HTMX Integration

Most components support HTMX attributes for dynamic interactions: 
const html = button('Load More', {
  htmx: {
    get: '/api/items?page=2',
    target: '#items-list',
    swap: 'beforeend',
    trigger: 'click',
  },
});
Common HTMX attributes:
  • get, post, put, delete - HTTP methods
  • target - CSS selector for target element
  • swap - How to swap content (innerHTML, beforeend, etc.)
  • trigger - Event that triggers the request
  • confirm - Confirmation dialog text

​
Styling

Components use Tailwind CSS classes. You can add custom classes with the className option: 
const html = card('Content', {
  className: 'bg-gradient-to-r from-blue-500 to-purple-500',
});
All component classes are designed to work with the default theme’s CSS variables:
  • text-primary, bg-primary - Primary brand color
  • text-secondary, bg-secondary - Secondary color
  • text-success, bg-success - Success/positive state
  • text-warning, bg-warning - Warning state
  • text-danger, bg-danger - Error/danger state
  • text-text-primary - Primary text color
  • text-text-secondary - Secondary text color
  • border-border - Border color
  • bg-surface - Surface background

​
Security

All user-provided content must be escaped to prevent XSS: 
import { escapeHtml } from '@frontmcp/ui';

// In your template
const html = card(`
  <p>${escapeHtml(userInput)}</p>
`);
The escapeHtml function is also available as ctx.helpers.escapeHtml in template functions.

​
Component Groups

Many components have companion “group” functions for layouts: 
import { button, buttonGroup, card, cardGroup, badge, badgeGroup } from '@frontmcp/ui';

// Button group
const buttons = buttonGroup([
  button('Edit'),
  button('Delete', { variant: 'danger' }),
], { attached: true });

// Card grid
const cards = cardGroup([
  card('Card 1'),
  card('Card 2'),
], { direction: 'horizontal', gap: 'md' });

// Badge list
const badges = badgeGroup([
  badge('Tag 1'),
  badge('Tag 2'),
  badge('Tag 3'),
]);