From 82048549861e9450671755852e8249c0b220f49e Mon Sep 17 00:00:00 2001
From: Danny White <3104761+dnywh@users.noreply.github.com>
Date: Wed, 30 Sep 2026 15:40:50 +1000
Subject: [PATCH] docs(design-system): document create actions in comboboxes
 (#51061)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Studio lets people create an item while selecting one, but the design
system does not document this pattern.

## Solution

Document the create action in the Combobox guide with a focused example.
The action sits below the options and leaves the current selection
unchanged. Products can connect it to their own creation flow.

| After |
| --- |
| <img width="552" height="352" alt="CleanShot 2026-09-30 at 10 57
46@2x"
src="https://github.com/user-attachments/assets/69c8069c-d4f9-45e2-b3a1-6e5431e2aff9"
/> |

## Review instructions

1. Open the design system Combobox page and find “[Create from
list](https://design-system-git-dnywh-document-select-create-action-supabase.vercel.app/design-system/docs/components/combobox#create-from-list)”.
2. Select a bucket, then choose “New bucket”. Because it’s just an
example, the selector closes without replacing the selected bucket.

## Checklist

- [x] I have read
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md).


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a combobox example with a separate “New bucket” action. Choosing
it closes the menu without changing the current selection; choosing an
existing bucket updates the selection.
* Added documentation showing how to use this create-action pattern,
including guidance on labeling and positioning the action.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../content/docs/components/combobox.mdx      |  6 ++
 .../example/combobox-create-option.tsx        | 71 +++++++++++++++++++
 apps/design-system/registry/examples.ts       |  6 ++
 3 files changed, 83 insertions(+)
 create mode 100644 apps/design-system/registry/default/example/combobox-create-option.tsx

diff --git a/apps/design-system/content/docs/components/combobox.mdx b/apps/design-system/content/docs/components/combobox.mdx
index 3ad33b0124e..5b00f003667 100644
--- a/apps/design-system/content/docs/components/combobox.mdx
+++ b/apps/design-system/content/docs/components/combobox.mdx
@@ -132,3 +132,9 @@ You can create a responsive combobox by using the `<Popover />` on desktop and t
 ### Form
 
 <ComponentPreview name="combobox-form" />
+
+### Create from list
+
+When users can create an option while choosing one, give the action a clear verb label and place it at the bottom of the list, separated from the existing options. Keep the current selection in place while they create the new option.
+
+<ComponentPreview name="combobox-create-option" peekCode wide />
diff --git a/apps/design-system/registry/default/example/combobox-create-option.tsx b/apps/design-system/registry/default/example/combobox-create-option.tsx
new file mode 100644
index 00000000000..01fa6b5adc7
--- /dev/null
+++ b/apps/design-system/registry/default/example/combobox-create-option.tsx
@@ -0,0 +1,71 @@
+'use client'
+
+import { Check, Plus } from 'lucide-react'
+import { useState } from 'react'
+import {
+  ComboboxTrigger,
+  Command,
+  CommandGroup,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from 'ui'
+
+const buckets = ['Images', 'Exports']
+
+export default function ComboboxCreateOption() {
+  const [selectedBucket, setSelectedBucket] = useState('')
+  const [isListOpen, setIsListOpen] = useState(false)
+
+  return (
+    <Popover open={isListOpen} onOpenChange={setIsListOpen}>
+      <PopoverTrigger asChild>
+        <ComboboxTrigger
+          aria-expanded={isListOpen}
+          data-state={isListOpen ? 'open' : 'closed'}
+          className="w-[240px]"
+        >
+          {selectedBucket || 'Select a bucket'}
+        </ComboboxTrigger>
+      </PopoverTrigger>
+      <PopoverContent className="w-[240px] p-0" align="start">
+        <Command>
+          <CommandList>
+            <CommandGroup>
+              {buckets.map((bucket) => (
+                <CommandItem
+                  key={bucket}
+                  value={bucket}
+                  className="cursor-pointer justify-between"
+                  onSelect={() => {
+                    setSelectedBucket(bucket)
+                    setIsListOpen(false)
+                  }}
+                >
+                  {bucket}
+                  {selectedBucket === bucket && <Check size={14} />}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+            <CommandSeparator />
+            <CommandGroup>
+              <CommandItem
+                className="cursor-pointer"
+                onSelect={() => {
+                  setIsListOpen(false)
+                  // Open the creation flow here without changing the selected bucket.
+                }}
+              >
+                <Plus size={14} className="mr-2" />
+                New bucket
+              </CommandItem>
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  )
+}
diff --git a/apps/design-system/registry/examples.ts b/apps/design-system/registry/examples.ts
index 256eaa8f60f..0a47eeaa6c8 100644
--- a/apps/design-system/registry/examples.ts
+++ b/apps/design-system/registry/examples.ts
@@ -385,6 +385,12 @@ export const examples: Registry = [
     registryDependencies: ['command'],
     files: ['example/combobox-demo.tsx'],
   },
+  {
+    name: 'combobox-create-option',
+    type: 'components:example',
+    registryDependencies: ['command'],
+    files: ['example/combobox-create-option.tsx'],
+  },
   {
     name: 'combobox-dropdown-menu',
     type: 'components:example',