ControlCloud

Overview

The ControlCloud component provides a dynamic way to display active filters as interactive pills. It's designed to show users what filters are currently applied to their data, with keyboard navigation, removal capabilities, and customizable formatting for enhanced data filtering interfaces.

Usage

import { ControlCloud } from "@unkey/ui";
 
export default function MyComponent() {
  const [filters, setFilters] = useState<FilterValue[]>([]);
  
  const removeFilter = (id: string) => {
    setFilters(filters.filter(f => f.id !== id));
  };
  
  const updateFilters = (newFilters: FilterValue[]) => {
    setFilters(newFilters);
  };
  
  const formatFieldName = (field: string): string => {
    return field.charAt(0).toUpperCase() + field.slice(1);
  };
  
  return (
    <ControlCloud
      filters={filters}
      removeFilter={removeFilter}
      updateFilters={updateFilters}
      formatFieldName={formatFieldName}
    />
  );
}

Examples

Basic ControlCloud

A simple example showing basic filter pills for status and method.

1
2
3
4
5
6
7
8
9

 <div className="w-full max-w-2xl border border-gray-6 rounded-lg">
  <ControlCloud
    filters={filters}
    removeFilter={removeFilter}
    updateFilters={updateFilters}
    formatFieldName={formatFieldName}
  />
  <div className="p-4 text-sm text-gray-11">Active filters: {filters.length}</div>
</div>

Time-Based Filters

Example with time range filters that use the TimestampInfo component for display.

1
2
3
4
5
6
7
8
9

<div className="w-full max-w-2xl border border-gray-6 rounded-lg">
  <ControlCloud
    filters={filters}
    removeFilter={removeFilter}
    updateFilters={updateFilters}
    formatFieldName={formatFieldName}
  />
  <div className="p-4 text-sm text-gray-11">Time range filters applied</div>
</div>

Multiple Filter Types

Demonstrates different filter types including status, method, path, and duration with custom value formatting.

1
2
3
4
5
6
7
8
9
10
11
12

<div className="w-full max-w-2xl border border-gray-6 rounded-lg">
  <ControlCloud
    filters={filters}
    removeFilter={removeFilter}
    updateFilters={updateFilters}
    formatFieldName={formatFieldName}
    formatValue={formatValue}
  />
  <div className="p-4 text-sm text-gray-11">
    Mixed filter types: status, method, path, and duration
  </div>
</div>

Empty State

When no filters are applied, the component is hidden entirely.

1
2
3
4
5
6
7
8
9
10
11

<div className="w-full max-w-2xl border border-gray-6 rounded-lg">
  <ControlCloud
    filters={filters}
    removeFilter={removeFilter}
    updateFilters={updateFilters}
    formatFieldName={formatFieldName}
  />
  <div className="p-4 text-sm text-gray-11">
    No filters applied (component is hidden when empty)
  </div>
</div>

Interactive Example

Add filters dynamically and test keyboard navigation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<div className="w-full max-w-2xl space-y-4">
  <div className="flex gap-2">
    <button
      type="button"
      onClick={() => addFilter("status", "200")}
      className="px-3 py-1 text-xs bg-gray-3 rounded hover:bg-gray-4"
    >
      Add Status Filter
    </button>
    <button
      type="button"
      onClick={() => addFilter("method", "GET")}
      className="px-3 py-1 text-xs bg-gray-3 rounded hover:bg-gray-4"
    >
      Add Method Filter
    </button>
    <button
      type="button"
      onClick={() => addFilter("path", "/api/users")}
      className="px-3 py-1 text-xs bg-gray-3 rounded hover:bg-gray-4"
    >
      Add Path Filter
    </button>
  </div>
  <div className="border border-gray-6 rounded-lg">
    <ControlCloud
      filters={filters}
      removeFilter={removeFilter}
      updateFilters={updateFilters}
      formatFieldName={formatFieldName}
    />
    <div className="p-4 text-sm text-gray-11">
      Click buttons above to add filters, then use keyboard navigation (
      {isMac ? "⌥+⇧+C" : "Alt+Shift+C"} to focus)
    </div>
  </div>
</div>

Features

• Interactive Filter Pills: Each filter is displayed as a removable pill with field name, operator, and value
• Keyboard Navigation: Full keyboard support with arrow keys and vim-style navigation (h,j,k,l)
• Keyboard Shortcuts:
  • ⌥+⇧+D to clear all filters and set default time range
  • ⌥+⇧+C to focus the first filter pill
• Time Display: Automatic timestamp formatting for time-based filters
• Custom Formatting: Configurable field name and value formatting
• Accessibility: Proper ARIA attributes and screen reader support
• Responsive Design: Adapts to different screen sizes

Props

FilterValue Type

type FilterValue = {
  id: string;
  field: string;
  operator: "is" | "contains" | "gt" | "lt" | "gte" | "lte" | "startsWith" | "endsWith";
  value: string | number;
  metadata?: {
    colorClass?: string;
    icon?: React.ReactNode;
  };
};

Structure

The ControlCloud component is composed of:

1. Filter Pills Container - Wrapper for all filter pills
2. Individual Filter Pills - Each filter displayed as a removable pill
3. Keyboard Navigation System - Handles focus and navigation
4. Time Display Components - Special formatting for time-based filters

Styling

The component includes default styling with:

• Consistent pill styling with hover and focus states
• Color-coded filter types for visual distinction
• Responsive design that adapts to container width
• Dark mode support with appropriate color schemes
• Focus indicators for keyboard navigation
• Customizable through className props

Custom Styling

You can customize the appearance using the className prop:

<ControlCloud
  filters={filters}
  removeFilter={removeFilter}
  updateFilters={updateFilters}
  formatFieldName={formatFieldName}
  className="custom-control-cloud"
/>

Keyboard Navigation

The ControlCloud component provides comprehensive keyboard navigation:

• Arrow Keys: Navigate between filter pills
• Vim Keys:
  • h / ←: Move left
  • l / →: Move right
  • j / ↓: Move down
  • k / ↑: Move up
• Delete/Backspace: Remove focused filter pill
• Tab: Standard tab navigation
• Escape: Clear focus

Keyboard Shortcuts

• ⌥+⇧+D: Clear all filters and set a default time range (endTime = now, startTime = now - historicalWindow)
• ⌥+⇧+C: Focus the first filter pill for keyboard navigation

Accessibility

The ControlCloud component is built with accessibility in mind:

• Keyboard Navigation: Full keyboard support for all interactions
• Screen Reader Support: Proper ARIA labels and announcements
• Focus Management: Clear focus indicators and logical tab order
• High Contrast: Maintains proper contrast ratios
• Semantic HTML: Uses appropriate HTML elements and roles