@arg/ui

@arg/ui gives a React app the same core controls Arg uses. Import it directly in a .tsx or .jsx workspace file. There is no package installation or stylesheet import: the React preview supplies the module and adds its styles when you use it.

import { Button, Card, FormInput } from "@arg/ui";

The controls inherit the viewer’s light, focus, or dark Arg theme. Buttons, cards, form controls, and compatibility primitives forward their documented DOM props and refs, so you can compose them with your own workspace CSS.

Components

Export	Use it for
`Button`	Primary, secondary, ghost, outlined, and danger actions
`IconButton`	Compact toolbar or icon-only actions
`Card`	Surface, muted, or unstyled content containers
`FormInput`, `Input`	Text and native input controls with errors and an optional leading icon
`FormTextarea`, `Textarea`	Multi-line input with an optional error
`KeyboardShortcut`	An inline or badge-style keyboard shortcut label
`Dropdown`	A controlled, optionally searchable select menu
`ContextMenu`	A viewport-positioned menu with items, submenus, checkboxes, and steppers

Buttons

import { Button, IconButton } from "@arg/ui";

export default function Actions() {
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <Button variant="primary">Save</Button>
      <Button variant="outlined">Preview</Button>
      <Button variant="danger" isLoading={false}>
        Delete
      </Button>
      <IconButton aria-label="More options">...</IconButton>
    </div>
  );
}

`Button` props

Button accepts native button props plus:

Prop	Type	Default
`variant`	`"primary" \| "secondary" \| "ghost" \| "outlined" \| "danger" \| "danger-outlined"`	`"primary"`
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`isLoading`	`boolean`	`false`
`leftIcon`	`ReactNode`	None
`rightIcon`	`ReactNode`	None

Loading replaces the left icon with a spinner and disables the button. buttonClassName({ variant, size, className }) returns the same class set when you need button styling on a compatible custom element. IconButton accepts native button props, size: "sm" | "md" | "lg", and variant: "ghost" | "solid". The defaults are "md" and "ghost". Give every icon-only button an aria-label.

Cards

import { Card } from "@arg/ui";

export default function ProjectCard() {
  return (
    <Card as="a" href="#details" variant="surface" padding="md" radius="xl" interactive>
      <h2>Launch plan</h2>
      <p>Eight tasks are ready for review.</p>
    </Card>
  );
}

Prop	Type	Default
`variant`	`"surface" \| "muted" \| "ghost"`	`"surface"`
`padding`	`"none" \| "sm" \| "base" \| "md" \| "lg"`	`"md"`
`radius`	`"lg" \| "xl" \| "2xl"`	`"xl"`
`interactive`	`boolean`	`false`
`as`	A React element type	`"div"`

Card also forwards element attributes. Set as="a" when you pass href.

Form controls

import { FormInput, FormTextarea } from "@arg/ui";

export default function ProfileFields() {
  return (
    <form style={{ display: "grid", gap: 12 }}>
      <FormInput
        aria-label="Project name"
        placeholder="Project name"
        error="A project name is required"
      />
      <FormTextarea aria-label="Summary" placeholder="Summary" rows={5} />
    </form>
  );
}

Both controls accept their native input or textarea attributes. Their variant is "default", "medium", or "small" and defaults to "default". Pass error to show an error state and message. FormInput also accepts leftIcon; FormTextarea defaults to four rows. Input is an alias for FormInput. Textarea is an alias for FormTextarea. Dropdown is controlled: your component owns value, and onChange receives the selected option’s string value.

import { useState } from "react";
import { Dropdown } from "@arg/ui";

const options = [
  { value: "comfortable", label: "Comfortable" },
  { value: "compact", label: "Compact", description: "Fit more rows on screen" },
];

export default function DensityPicker() {
  const [density, setDensity] = useState("comfortable");

  return (
    <Dropdown
      options={options}
      value={density}
      onChange={setDensity}
      triggerVariant="field"
      searchable
      searchPlaceholder="Find a density..."
    />
  );
}

Prop	Type	Default
`id`	`string`	Generated
`options`	`{ value, label, description?, icon? }[]`	Required
`value`	`string`	Required
`onChange`	`(value: string) => void`	Required
`placeholder`	`string`	`"Select..."`
`disabled`	`boolean`	`false`
`size`	`"sm" \| "md"`	`"md"`
`triggerVariant`	`"default" \| "field" \| "ghost"`	`"default"`
`searchable`	`boolean`	`false`
`searchPlaceholder`	`string`	`"Search..."`
`menuMinWidth`	`number`	Trigger width, at least 120 px
`footerAction`	`{ label, icon?, onSelect, disabled? }`	None
`className`	`string`	None
`triggerClassName`	`string`	None

The menu opens in a portal, flips when space is tight, and stays inside the viewport. It supports arrow keys, Home, End, Enter, Escape, and type filtering when searchable is on. Render ContextMenu only while you have an anchor position. Clear that position in onClose.

import { useState } from "react";
import { ContextMenu } from "@arg/ui";

export default function FileRow() {
  const [menu, setMenu] = useState<{ x: number; y: number } | null>(null);
  const [pinned, setPinned] = useState(false);

  return (
    <div
      onContextMenu={(event) => {
        event.preventDefault();
        setMenu({ x: event.clientX, y: event.clientY });
      }}
    >
      Right-click this row
      {menu ? (
        <ContextMenu
          position={menu}
          ariaLabel="File actions"
          onClose={() => setMenu(null)}
          items={[
            { kind: "header", id: "file", label: "File" },
            { kind: "item", id: "open", label: "Open", onClick: () => {} },
            {
              kind: "checkbox",
              id: "pin",
              label: "Pinned",
              checked: pinned,
              onClick: () => setPinned((value) => !value),
            },
            { kind: "separator", id: "divider" },
            { kind: "item", id: "delete", label: "Delete", danger: true, onClick: () => {} },
          ]}
        />
      ) : null}
    </div>
  );
}

ContextMenu accepts position, items, and onClose, plus size: "sm" | "md", align: "start" | "end", autoFocus, and ariaLabel. The defaults are "md", "start", and false.

Item kind	Main fields
`item`	`id`, `label`, `onClick`, `icon?`, `trailingIcon?`, `shortcut?`, `disabled?`, `danger?`
`checkbox`	`id`, `label`, `checked`, `onClick`, `icon?`, `shortcut?`
`submenu`	`id`, `label`, `items`, `icon?`
`stepper`	`id`, `label`, `value`, increment and decrement callbacks, optional reset and disabled states
`header`	`id`, `label`
`separator`	`id`

The menu and its submenus stay inside the viewport. Outside clicks and Escape call onClose, and keyboard navigation covers menu items and submenus.

Keyboard shortcuts

import { KeyboardShortcut } from "@arg/ui";

<KeyboardShortcut variant="badge">⌘K</KeyboardShortcut>;

variant is "inline" or "badge" and defaults to "inline".

Compatibility exports

Existing apps may still import Badge, Heading, Text, Stack, CardHeader, CardTitle, CardDescription, CardContent, and CardFooter. These exports remain available for compatibility, but they are deprecated. New apps should compose semantic HTML inside Card and use their own CSS for layout and typography.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Components

Buttons

`Button` props

Cards

Form controls

Context menu

Keyboard shortcuts

Compatibility exports

​Components

​Buttons

​Button props

​Cards

​Form controls

​Dropdown

​Dropdown props

​Context menu

​Keyboard shortcuts

​Compatibility exports

​Related

Components

Buttons

`Button` props

Cards

Form controls

Dropdown

`Dropdown` props

Context menu

Keyboard shortcuts

Compatibility exports

Related