Harmonizing gpui-component API with the ShadCN canonical spec (to support quoin and cross‑framework UI)

[elcoosp]

Hi! I’m the author of quoin, a project that aims to provide a single canonical API for all ShadCN‑style Rust UI libraries, built on top of gpui-component. The idea is to use compile‑time macros so that developers can write a component once and generate it for GPUI, Leptos, or Dioxus.

To make this possible, the underlying libraries need to align their APIs with the original ShadCN spec. I’ve done a full side‑by‑side review of gpui-component, leptos-shadcn-ui, and shadcn-dioxus. The goal is to identify gaps and naming inconsistencies and gradually converge toward a shared standard.

I’d love to open a discussion about what changes could be made in gpui-component to move in that direction, and whether the maintainers would be open to contributions that implement them.

Key Findings for gpui-component

1. Variant naming – The current names differ from the canonical ShadCN set:

   • primary → default
   • danger → destructive
   • text → link
     This affects Button, Alert, Tag, etc.

2. Component composition – Some components currently use a builder‑only pattern (e.g., .item(|item| …) for Accordion). However, the canonical spec uses distinct child components (AccordionItem, AccordionTrigger, AccordionContent).
   Adding those sub‑components (while keeping the existing API) would make the library easier to target with macros.

3. State management – Many components manage state internally via Entity and subscriptions (e.g., CalendarState, InputState). The canonical approach uses controlled/uncontrolled props with on_change callbacks. A complementary API that accepts an optional selected/value signal would greatly simplify cross‑framework code generation. This is already partially present in the declarative Dialog and AlertDialog.

4. Missing core ShadCN components
   I identified several components that are present in the other two libraries but absent in gpui-component:

   • Card (GroupBox is similar but not identical)
   • Carousel
   • Combobox (though a searchable Select exists)
   • Command palette
   • Empty state
   • Menubar
   • NavigationMenu
   • ScrollArea (currently just a CSS utility)
   • Separator
   • Sidebar (already partially present but not as a provider‑based system)
     Adding these would make gpui-component a complete ShadCN implementation.

5. Minor inconsistencies

   • Avatar should support AvatarImage and AvatarFallback children, not just a .src() string.
   • Badge uses .count() and .dot() – these could be part of a BadgeVariant or kept as extras, but a standard Badge variant prop would help.
   • Checkbox lacks an indeterminate state.
   • RadioGroup and Tabs rely on index‑based selection rather than string values.
   • Button is missing a loading prop.

How This Helps quoin and the Ecosystem

If gpui-component adopts the canonical ShadCN naming and composition patterns, quoin (and any other tool) can generate its components directly without hundreds of lines of polyfills. The same macros could target Leptos or Dioxus libraries with near‑trivial backend modules.

More importantly, it makes the ShadCN ecosystem in Rust consistent, so that developers moving between frameworks don’t have to relearn APIs.

What I’m Proposing

I’d like to contribute PRs that:

• Introduce canonical sub‑components (e.g., AccordionItem, AccordionTrigger, AccordionContent) alongside the existing APIs (non‑breaking).
• Add missing components (Card, Separator, etc.) with standardised props.
• Optionally, add controlled/uncontrolled prop styles (e.g., on_change callbacks) to existing stateful components.
• Rename variants to match ShadCN, possibly with deprecation warnings for the old names.

All changes would be designed to be backwards‑compatible as much as possible.

I’d love to hear the maintainers’ thoughts. Is this direction acceptable? Are there any concerns about the scope or timeline? I’m happy to collaborate and help with the implementation.

---

Thank you for building gpui-component – it’s a fantastic library, and I’m excited about its potential as the GPUI‑native ShadCN offering.

---

[huacnlee]

Maintaining a broad API similar to Shadcn has always been part of my plan. However, the reality is that Shadcn and GPUI Component offer fundamentally different mechanisms, such as DataTable and List. GPUI Component prioritizes high performance even with large-scale data, making it suitable for complex applications. Shadcn's design is flexible; component styles can even be customized after installation, which is unlikely to be possible in GPUI Component (due to different architectures).

In fact, the current API design also references component designs from macOS and Windows, as well as other popular GUI frameworks.

Therefore, my answer is that these changes will depend on the situation. PRs are welcome, but specific changes will be determined on a case-by-case basis.