Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

Add Studio Explorer toolbar (#48925)

Saxon Fletcherfb80d8cf862b
diff --git a/apps/studio/.claude/skills/explorer/SKILL.md b/apps/studio/.claude/skills/explorer/SKILL.md
new file mode 100644
index 00000000000..3a62f2dfe19
--- /dev/null
+++ b/apps/studio/.claude/skills/explorer/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: explorer
+description: Build and modify Studio Explorer surfaces, including notebooks, chats, SQL snippets, query cells, and their shared toolbar patterns.
+---
+
+# Studio Explorer
+
+Use this skill when working in `apps/studio/components/interfaces/Explorer` or building notebook, chat, snippet, or query-cell UI for Explorer.
+
+Explorer UI is Studio-specific. Keep its components under `apps/studio/components/interfaces/Explorer`; do not move them into `ui-patterns` or duplicate them in the design-system app.
+
+## Explorer toolbar
+
+Import the toolbar primitives from:
+
+```tsx
+import {
+ ExplorerToolbar,
+ ExplorerToolbarAction,
+ ExplorerToolbarActions,
+ ExplorerToolbarIcon,
+ ExplorerToolbarTitle,
+} from '@/components/interfaces/Explorer/ExplorerToolbar'
+```
+
+Compose the toolbar from slots rather than adding resource-specific props:
+
+```tsx
+<ExplorerToolbar aria-label="Query toolbar">
+ <ExplorerToolbarIcon>{/* decorative resource icon */}</ExplorerToolbarIcon>
+ <ExplorerToolbarTitle>{/* static or editable title */}</ExplorerToolbarTitle>
+ <ExplorerToolbarActions>
+ {/* badges, source controls, display controls, and direct actions */}
+ <ExplorerToolbarAction aria-label="Run query" icon={<Play />} />
+ </ExplorerToolbarActions>
+</ExplorerToolbar>
+```
+
+- The row defaults to 40px and follows `--header-height` at the `md` breakpoint.
+- Use `ExplorerToolbarAction` for compact direct actions. Icon-only actions are 28px wide automatically.
+- Keep execution, persistence, source selection, and other resource state in the consuming Explorer surface.
+- Extend layouts with children and `className`; avoid boolean props for resource-specific variants.
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx b/apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx
new file mode 100644
index 00000000000..b1cc53ed922
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx
@@ -0,0 +1,84 @@
+import { render, screen, within } from '@testing-library/react'
+import { createRef } from 'react'
+import { describe, expect, it } from 'vitest'
+
+import {
+ ExplorerToolbar,
+ ExplorerToolbarAction,
+ ExplorerToolbarActions,
+ ExplorerToolbarIcon,
+ ExplorerToolbarTitle,
+} from './index'
+
+describe('ExplorerToolbar', () => {
+ it('composes the resource icon, title, direct actions, and custom controls', () => {
+ render(
+ <ExplorerToolbar aria-label="Explorer query toolbar">
+ <ExplorerToolbarIcon>Q</ExplorerToolbarIcon>
+ <ExplorerToolbarTitle>Weekly signups</ExplorerToolbarTitle>
+ <ExplorerToolbarActions>
+ <span data-testid="source-menu">Database</span>
+ <ExplorerToolbarAction aria-label="Run cell" icon={<span>R</span>} />
+ </ExplorerToolbarActions>
+ </ExplorerToolbar>
+ )
+
+ const toolbar = screen.getByRole('toolbar', { name: 'Explorer query toolbar' })
+ expect(toolbar).toHaveAttribute('data-slot', 'explorer-toolbar')
+ expect(toolbar.querySelector('[data-slot="explorer-toolbar-icon"]')).toHaveTextContent('Q')
+ expect(toolbar.querySelector('[data-slot="explorer-toolbar-title"]')).toHaveTextContent(
+ 'Weekly signups'
+ )
+ expect(within(toolbar).getByTestId('source-menu')).toBeInTheDocument()
+
+ const runAction = within(toolbar).getByRole('button', { name: 'Run cell' })
+ expect(runAction).toHaveAttribute('data-slot', 'explorer-toolbar-action')
+ expect(runAction).toHaveAttribute('data-size', 'tiny')
+ expect(runAction).toHaveClass('w-7', 'px-0')
+ })
+
+ it('supports labeled actions and forwards refs and native props', () => {
+ const actionRef = createRef<HTMLButtonElement>()
+
+ render(
+ <ExplorerToolbar
+ aria-label="Notebook toolbar"
+ className="custom-toolbar"
+ data-density="compact"
+ >
+ <ExplorerToolbarTitle>Authentication health</ExplorerToolbarTitle>
+ <ExplorerToolbarActions>
+ <ExplorerToolbarAction ref={actionRef} data-command="analyze">
+ Analyze
+ </ExplorerToolbarAction>
+ </ExplorerToolbarActions>
+ </ExplorerToolbar>
+ )
+
+ const toolbar = screen.getByRole('toolbar', { name: 'Notebook toolbar' })
+ const action = within(toolbar).getByRole('button', { name: 'Analyze' })
+
+ expect(toolbar).toHaveClass('custom-toolbar')
+ expect(toolbar).toHaveAttribute('data-density', 'compact')
+ expect(toolbar.querySelector('[data-slot="explorer-toolbar-actions"]')).toHaveClass('gap-px')
+ expect(action).toHaveAttribute('data-command', 'analyze')
+ expect(action).not.toHaveClass('w-7')
+ expect(actionRef.current).toBe(action)
+ })
+
+ it('defaults its height but lets a consumer drive it', () => {
+ const { rerender } = render(<ExplorerToolbar aria-label="Default height" />)
+
+ // The header height variable stays consumer-owned, but it carries a fallback
+ // so apps that leave it unset keep the default row instead of an invalid
+ // declaration the browser drops.
+ expect(screen.getByRole('toolbar')).toHaveClass('h-10')
+ expect(screen.getByRole('toolbar').className).toContain('var(--header-height,2.5rem)')
+
+ rerender(<ExplorerToolbar aria-label="Taller height" className="h-12" />)
+
+ const toolbar = screen.getByRole('toolbar')
+ expect(toolbar).toHaveClass('h-12')
+ expect(toolbar).not.toHaveClass('h-10')
+ })
+})
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx b/apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx
new file mode 100644
index 00000000000..6b21debb933
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx
@@ -0,0 +1,104 @@
+import React from 'react'
+import { Button, cn } from 'ui'
+
+export type ExplorerToolbarProps = React.ComponentProps<'div'>
+
+/**
+ * Shared toolbar row for Explorer resources such as notebooks and queries.
+ * Defaults to 40px and follows `--header-height` from the `md` breakpoint up, so
+ * a consumer that defines its own header height gets toolbars matching it. The
+ * fallback keeps the row at its default height in apps that leave the variable
+ * unset, rather than dropping the rule.
+ */
+const ExplorerToolbar = ({ className, role = 'toolbar', ...props }: ExplorerToolbarProps) => (
+ <div
+ data-slot="explorer-toolbar"
+ role={role}
+ className={cn(
+ 'flex h-10 w-full shrink-0 items-center gap-2 border-b bg-transparent px-3 md:min-h-[var(--header-height,2.5rem)]',
+ className
+ )}
+ {...props}
+ />
+)
+ExplorerToolbar.displayName = 'ExplorerToolbar'
+
+export type ExplorerToolbarIconProps = React.ComponentProps<'span'>
+
+/** Decorative resource icon shown before the toolbar title. */
+const ExplorerToolbarIcon = ({
+ 'aria-hidden': ariaHidden = true,
+ className,
+ ...props
+}: ExplorerToolbarIconProps) => (
+ <span
+ data-slot="explorer-toolbar-icon"
+ aria-hidden={ariaHidden}
+ className={cn('shrink-0 text-foreground-muted [&_svg]:size-3.5', className)}
+ {...props}
+ />
+)
+ExplorerToolbarIcon.displayName = 'ExplorerToolbarIcon'
+
+export type ExplorerToolbarTitleProps = React.ComponentProps<'div'>
+
+/** Flexible title region for static text or an editable resource name. */
+const ExplorerToolbarTitle = ({ className, ...props }: ExplorerToolbarTitleProps) => (
+ <div
+ data-slot="explorer-toolbar-title"
+ className={cn('min-w-0 flex-1 truncate text-sm', className)}
+ {...props}
+ />
+)
+ExplorerToolbarTitle.displayName = 'ExplorerToolbarTitle'
+
+export type ExplorerToolbarActionsProps = React.ComponentProps<'div'>
+
+/**
+ * Trailing region for direct actions and composite controls such as badges,
+ * source menus, and display configuration.
+ */
+const ExplorerToolbarActions = ({ className, ...props }: ExplorerToolbarActionsProps) => (
+ <div
+ data-slot="explorer-toolbar-actions"
+ className={cn('ml-auto flex shrink-0 items-center gap-px', className)}
+ {...props}
+ />
+)
+ExplorerToolbarActions.displayName = 'ExplorerToolbarActions'
+
+export type ExplorerToolbarActionProps = Omit<
+ React.ComponentPropsWithRef<typeof Button>,
+ 'size' | 'variant'
+>
+
+/**
+ * The standard tiny, text-style button used for a direct toolbar action.
+ * Icon-only actions receive the prototype's compact 28px width automatically.
+ */
+const ExplorerToolbarAction = ({
+ children,
+ className,
+ ref,
+ ...props
+}: ExplorerToolbarActionProps) => (
+ <Button
+ ref={ref}
+ data-slot="explorer-toolbar-action"
+ variant="text"
+ size="tiny"
+ className={cn(children == null && 'w-7 px-0', className)}
+ {...props}
+ >
+ {children}
+ </Button>
+)
+ExplorerToolbarAction.displayName = 'ExplorerToolbarAction'
+
+export {
+ ExplorerToolbar,
+ ExplorerToolbarAction,
+ ExplorerToolbarActions,
+ ExplorerToolbarIcon,
+ ExplorerToolbarTitle,
+}