Managing State

What kind of state do you need?

├── Need to sync with LLM? → data-llm attribute
│   (The model needs to know what user is viewing)
│
├── Simple key/value state? → useWidgetState
│   (Form inputs, selected items, flags — persisted in ChatGPT)
│
└── Complex state with actions? → createStore
    (Multiple related values, computed state, async actions)

import { useWidgetState } from "skybridge/web";

function CounterWidget() {
  const [state, setState] = useWidgetState({ count: 0 });

  if (!state) return null;

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={() => setState(prev => ({ count: prev.count + 1 }))}>
        Increment
      </button>
    </div>
  );
}

const [state, setState] = useWidgetState<T>(defaultState);

const [formData, setFormData] = useWidgetState({
  name: "",
  email: "",
  message: "",
});

const updateField = (field: string, value: string) => {
  setFormData(prev => ({ ...prev, [field]: value }));
};

const [selected, setSelected] = useWidgetState<Set<string>>(new Set());

const toggleItem = (id: string) => {
  setSelected(prev => {
    const next = new Set(prev);
    if (next.has(id)) next.delete(id);
    else next.add(id);
    return next;
  });
};

import { createStore } from "skybridge/web";

type CartItem = { id: string; name: string; price: number; quantity: number };

type CartState = {
  items: CartItem[];
  addItem: (item: Omit<CartItem, "quantity">) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  total: () => number;
  clear: () => void;
};

const useCartStore = createStore<CartState>((set, get) => ({
  items: [],

  addItem: (item) => set((state) => {
    const existing = state.items.find(existingItem => existingItem.id === item.id);
    if (existing) {
      return {
        items: state.items.map(existingItem =>
          existingItem.id === item.id ? { ...existingItem, quantity: existingItem.quantity + 1 } : existingItem
        ),
      };
    }
    return { items: [...state.items, { ...item, quantity: 1 }] };
  }),

  removeItem: (id) => set((state) => ({
    items: state.items.filter(item => item.id !== id),
  })),

  updateQuantity: (id, quantity) => set((state) => ({
    items: state.items.map(item =>
      item.id === id ? { ...item, quantity } : item
    ),
  })),

  total: () => get().items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  ),

  clear: () => set({ items: [] }),
}), { items: [] }); // Default state for first load

function CartWidget() {
  const items = useCartStore(state => state.items);
  const addItem = useCartStore(state => state.addItem);
  const total = useCartStore(state => state.total());

  return (
    <div>
      <ul>
        {items.map(item => (
          <li key={item.id}>{item.name} x{item.quantity}</li>
        ))}
      </ul>
      <p>Total: ${total}</p>
    </div>
  );
}

function ProductListWidget() {
  const [selected, setSelected] = useWidgetState<string | null>(null);
  const products = useToolInfo<Product[]>().output?.structuredContent.products;

  const selectedProduct = products?.find(product => product.id === selected);

  return (
    <div data-llm={selected
      ? `User selected: ${selectedProduct?.name}`
      : "User browsing product list"
    }>
      {products?.map(product => (
        <div
          key={product.id}
          onClick={() => setSelected(product.id)}
          data-llm={`Product: ${product.name} - $${product.price}`}
        >
          {product.name}
        </div>
      ))}
    </div>
  );
}

// Before: State lost on re-mount
const [selected, setSelected] = useState<string | null>(null);

// After: State persists
const [selected, setSelected] = useWidgetState<string | null>(null);