feat(Select): add position prop & align-item

.changeset/select-item-aligned.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+feat(Select): add item-aligned positioning

docs/content/components/select.md

@@ -4,7 +4,7 @@ description: Enables users to pick from a list of options displayed in a dropdow
 ---
 
 <script>
-	import { APISection, ComponentPreview, SelectDemo, SelectDemoCustomAnchor, SelectDemoMultiple, SelectDemoTransition, SelectDemoAutoScrollDelay, Callout, SelectDemoCustomValue } from '$lib/components'
+	import { APISection, ComponentPreview, SelectDemo, SelectDemoCustomAnchor, SelectDemoMultiple, SelectDemoTransition, SelectDemoAutoScrollDelay, Callout, SelectDemoCustomValue, SelectDemoItemAligned } from '$lib/components'
 	let { schemas } = $props()
 </script>
 
@@ -290,6 +290,32 @@ You can opt-out of this behavior by instead using the `Select.ContentStatic` com
 
 When using this component, you'll need to handle the positioning of the content yourself. Keep in mind that using `Select.Portal` alongside `Select.ContentStatic` may result in some unexpected positioning behavior, feel free to not use the portal or work around it.
 
+## Item-Aligned Positioning
+
+By default, `Select.Content` uses [Floating UI](https://floating-ui.com/) to anchor the list to the trigger, much like a popover. When you set `position="item-aligned"`, the content is instead placed so that the currently selected item sits directly over the trigger, mirroring the behavior of a native `<select>` on macOS.
+
+```svelte /position="item-aligned"/
+<Select.Content position="item-aligned">
+	<Select.ScrollUpButton />
+	<Select.Viewport>
+		<Select.Item />
+	</Select.Viewport>
+	<Select.ScrollDownButton />
+</Select.Content>
+```
+
+In this mode, the `side`, `sideOffset`, `align`, `alignOffset`, `avoidCollisions`, and other collision-related props are ignored. The `data-side` attribute on the content is set to `none` so that side-specific animations or styles don't run — keep this in mind if your styles depend on `data-[side=...]` selectors.
+
+If the list is taller than the viewport, `Select.Viewport`'s scroll position is adjusted automatically to keep the selected item aligned with the trigger, and the remaining items can be scrolled into view using `Select.ScrollUpButton` and `Select.ScrollDownButton`. For this reason, the `Select.Viewport` and scroll button components should always be included in your structure when using this mode.
+
+<ComponentPreview name="select-demo-item-aligned" componentName="Select">
+
+{#snippet preview()}
+<SelectDemoItemAligned />
+{/snippet}
+
+</ComponentPreview>
+
 ## Custom Anchor
 
 By default, the `Select.Content` is anchored to the `Select.Trigger` component, which determines where the content is positioned.

docs/src/lib/components/demos/index.ts

@@ -44,6 +44,7 @@ export { default as SelectDemoAutoScrollDelay } from "./select-demo-auto-scroll-
 export { default as SelectDemoCustom } from "./select-demo-custom.svelte";
 export { default as SelectDemoCustomAnchor } from "./select-demo-custom-anchor.svelte";
 export { default as SelectDemoCustomValue } from "./select-demo-custom-value.svelte";
+export { default as SelectDemoItemAligned } from "./select-demo-item-aligned.svelte";
 export { default as SelectDemoMultiple } from "./select-demo-multiple.svelte";
 export { default as SelectDemoTransition } from "./select-demo-transition.svelte";
 export { default as MenubarDemo } from "./menubar-demo.svelte";

docs/src/lib/components/demos/select-demo-item-aligned.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+	import { Select } from "bits-ui";
+	import Check from "phosphor-svelte/lib/Check";
+	import Palette from "phosphor-svelte/lib/Palette";
+	import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
+	import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
+	import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
+
+	const themes = [
+		{ value: "light-monochrome", label: "Light Monochrome" },
+		{ value: "dark-green", label: "Dark Green" },
+		{ value: "svelte-orange", label: "Svelte Orange" },
+		{ value: "punk-pink", label: "Punk Pink" },
+		{ value: "ocean-blue", label: "Ocean Blue", disabled: true },
+		{ value: "sunset-orange", label: "Sunset Orange" },
+		{ value: "sunset-red", label: "Sunset Red" },
+		{ value: "forest-green", label: "Forest Green" },
+		{ value: "lavender-purple", label: "Lavender Purple", disabled: true },
+		{ value: "mustard-yellow", label: "Mustard Yellow" },
+		{ value: "slate-gray", label: "Slate Gray" },
+		{ value: "neon-green", label: "Neon Green" },
+		{ value: "coral-reef", label: "Coral Reef" },
+		{ value: "midnight-blue", label: "Midnight Blue" },
+		{ value: "crimson-red", label: "Crimson Red" },
+		{ value: "mint-green", label: "Mint Green" },
+		{ value: "pastel-pink", label: "Pastel Pink" },
+		{ value: "golden-yellow", label: "Golden Yellow" },
+		{ value: "deep-purple", label: "Deep Purple" },
+		{ value: "turquoise-blue", label: "Turquoise Blue" },
+		{ value: "burnt-orange", label: "Burnt Orange" },
+	];
+
+	let value = $state("mustard-yellow");
+</script>
+
+<Select.Root type="single" items={themes} bind:value allowDeselect={false}>
+	<Select.Trigger
+		class="h-input rounded-9px border-border-input bg-background data-placeholder:text-foreground-alt/50 inline-flex w-[296px] touch-none select-none items-center border px-[11px] text-sm transition-colors"
+		aria-label="Select a theme"
+	>
+		<Palette class="text-muted-foreground mr-[9px] size-6" />
+		<Select.Value placeholder="Select a theme" />
+		<CaretUpDown class="text-muted-foreground ml-auto size-6" />
+	</Select.Trigger>
+	<Select.Portal>
+		<Select.Content
+			position="item-aligned"
+			class="focus-override border-muted bg-background shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 outline-hidden z-50 w-[var(--bits-select-anchor-width)] min-w-[var(--bits-select-anchor-width)] select-none rounded-xl border px-1 py-3"
+		>
+			<Select.ScrollUpButton class="flex w-full items-center justify-center">
+				<CaretDoubleUp class="size-3" />
+			</Select.ScrollUpButton>
+			<Select.Viewport class="p-1">
+				{#each themes as theme, i (i + theme.value)}
+					<Select.Item
+						class="rounded-button data-highlighted:bg-muted outline-hidden data-disabled:opacity-50 flex h-10 w-full select-none items-center py-3 pl-[36px] pr-1.5 text-sm capitalize"
+						value={theme.value}
+						label={theme.label}
+						disabled={theme.disabled}
+					>
+						{#snippet children({ selected })}
+							{theme.label}
+							{#if selected}
+								<div class="ml-auto">
+									<Check aria-label="check" />
+								</div>
+							{/if}
+						{/snippet}
+					</Select.Item>
+				{/each}
+			</Select.Viewport>
+			<Select.ScrollDownButton class="flex w-full items-center justify-center">
+				<CaretDoubleDown class="size-3" />
+			</Select.ScrollDownButton>
+		</Select.Content>
+	</Select.Portal>
+</Select.Root>

docs/src/lib/content/api-reference/extended-types/select/index.ts

@@ -1,4 +1,5 @@
 export { default as ItemsProp } from "./items-prop.md"
 export { default as DelayProp } from "./delay-prop.md"
+export { default as SelectPositionProp } from "./position-prop.md"
 export { default as SelectValueChildSnippetProps } from "./select-value-child-snippet-props.md"
 export { default as SelectValueChildrenSnippetProps } from "./select-value-children-snippet-props.md"

docs/src/lib/content/api-reference/extended-types/select/position-prop.md

@@ -0,0 +1,3 @@
+```ts
+"popper" | "item-aligned"
+```

docs/src/lib/content/api-reference/select.api.ts

@@ -41,6 +41,7 @@ import { ComboboxScrollAlignmentProp } from "./extended-types/combobox/index.js"
 import {
 	DelayProp,
 	ItemsProp,
+	SelectPositionProp,
 	SelectValueChildSnippetProps,
 	SelectValueChildrenSnippetProps,
 } from "./extended-types/select/index.js";
@@ -151,6 +152,13 @@ export const content = defineComponentApiSchema<SelectContentPropsWithoutHTML>({
 			description:
 				"Whether or not the select should loop through items when reaching the end.",
 		}),
+		position: defineEnumProp({
+			options: ["popper", "item-aligned"],
+			default: "popper",
+			description:
+				"Controls how the content is positioned. `popper` uses Floating UI to anchor the content to the trigger, supporting `side`, `align`, `sideOffset`, and the collision props. `item-aligned` aligns the currently selected item's center with the trigger's center, like a native `<select>` on macOS — the `side`, `sideOffset`, `align`, `alignOffset`, and collision props are ignored, and `data-side` is set to `none`.",
+			definition: SelectPositionProp,
+		}),
 		forceMount: forceMountProp,
 		preventScroll: definePropSchema({
 			...preventScrollProp,
@@ -190,6 +198,13 @@ export const contentStatic = defineComponentApiSchema<SelectContentStaticPropsWi
 			description:
 				"Whether or not the select should loop through items when reaching the end.",
 		}),
+		position: defineEnumProp({
+			options: ["popper", "item-aligned"],
+			default: "popper",
+			description:
+				"Controls how the content is positioned. `item-aligned` aligns the selected item's center with the trigger's center, like a native `<select>` on macOS. When this is active, `data-side` is set to `none`.",
+			definition: SelectPositionProp,
+		}),
 		forceMount: forceMountProp,
 		...withChildProps({
 			elType: "HTMLDivElement",

docs/src/routes/select-test/+page.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+	import SelectDemoItemAligned from "$lib/components/demos/select-demo-item-aligned.svelte";
+</script>
+
+<div style="min-height: 300vh; padding: 20px; display: flex; flex-direction: column; gap: 0;">
+	<!-- Trigger near top -->
+	<div style="padding-top: 40px;">
+		<p style="margin-bottom: 8px; font-size: 12px; color: #888;">Trigger near top of viewport</p>
+		<SelectDemoItemAligned />
+	</div>
+
+	<!-- Trigger in middle -->
+	<div style="margin-top: 45vh;">
+		<p style="margin-bottom: 8px; font-size: 12px; color: #888;">Trigger near middle of viewport</p>
+		<SelectDemoItemAligned />
+	</div>
+
+	<!-- Trigger near bottom -->
+	<div style="margin-top: 45vh;">
+		<p style="margin-bottom: 8px; font-size: 12px; color: #888;">Trigger near bottom of viewport</p>
+		<SelectDemoItemAligned />
+	</div>
+</div>

packages/bits-ui/src/lib/bits/combobox/types.ts

@@ -1,6 +1,10 @@
 import type { BitsPrimitiveInputAttributes } from "$lib/shared/attributes.js";
 import type {
 	SelectBaseRootPropsWithoutHTML,
+	SelectContentProps,
+	SelectContentPropsWithoutHTML,
+	SelectContentStaticProps,
+	SelectContentStaticPropsWithoutHTML,
 	SelectMultipleRootPropsWithoutHTML,
 	SelectSingleRootPropsWithoutHTML,
 } from "$lib/bits/select/types.js";
@@ -34,11 +38,17 @@ export type ComboboxRootPropsWithoutHTML = ComboboxBaseRootPropsWithoutHTML &
 
 export type ComboboxRootProps = ComboboxRootPropsWithoutHTML;
 
+// Combobox doesn't support `position="item-aligned"` — item-aligned positioning
+// doesn't apply when the list is filtered by typing.
+export type ComboboxContentProps = Omit<SelectContentProps, "position">;
+export type ComboboxContentPropsWithoutHTML = Omit<SelectContentPropsWithoutHTML, "position">;
+export type ComboboxContentStaticProps = Omit<SelectContentStaticProps, "position">;
+export type ComboboxContentStaticPropsWithoutHTML = Omit<
+	SelectContentStaticPropsWithoutHTML,
+	"position"
+>;
+
 export type {
-	SelectContentProps as ComboboxContentProps,
-	SelectContentPropsWithoutHTML as ComboboxContentPropsWithoutHTML,
-	SelectContentStaticProps as ComboboxContentStaticProps,
-	SelectContentStaticPropsWithoutHTML as ComboboxContentStaticPropsWithoutHTML,
 	SelectItemProps as ComboboxItemProps,
 	SelectItemPropsWithoutHTML as ComboboxItemPropsWithoutHTML,
 	SelectItemSnippetProps as ComboboxItemSnippetProps,

packages/bits-ui/src/lib/bits/select/components/select-content-static.svelte

@@ -6,6 +6,7 @@
 	import { createId } from "$lib/internal/create-id.js";
 	import { noop } from "$lib/internal/noop.js";
 	import PopperLayerForceMount from "$lib/bits/utilities/popper-layer/popper-layer-force-mount.svelte";
+	import SelectItemAlignedContent from "./select-item-aligned-content.svelte";
 
 	const uid = $props.id();
 
@@ -19,6 +20,7 @@
 		child,
 		preventScroll = false,
 		style,
+		position = "popper",
 		...restProps
 	}: SelectContentStaticProps = $props();
 
@@ -30,12 +32,45 @@
 		),
 		onInteractOutside: boxWith(() => onInteractOutside),
 		onEscapeKeydown: boxWith(() => onEscapeKeydown),
+		position: boxWith(() => position),
 	});
 
 	const mergedProps = $derived(mergeProps(restProps, contentState.props));
+
+	function mountWrapper(node: HTMLElement) {
+		contentState.setContentWrapper(node);
+		return { destroy: () => contentState.setContentWrapper(null) };
+	}
 </script>
 
-{#if forceMount}
+{#if contentState.useItemAligned}
+	<SelectItemAlignedContent
+		{id}
+		ref={contentState.opts.ref}
+		enabled={contentState.root.opts.open.current}
+		shouldRender={contentState.shouldRender}
+		{preventScroll}
+		onEscapeKeydown={contentState.onEscapeKeydown}
+		onInteractOutside={contentState.onInteractOutside}
+		onOpenAutoFocus={contentState.onOpenAutoFocus}
+		onCloseAutoFocus={contentState.onCloseAutoFocus}
+		trapFocus={false}
+		loop={false}
+	>
+		{#snippet content({ props: layerProps })}
+			{@const contentProps = mergeProps(restProps, layerProps, contentState.props, { style })}
+			<div use:mountWrapper data-select-content-wrapper style="position: fixed; display: flex; flex-direction: column;">
+				{#if child}
+					{@render child({ props: contentProps, ...contentState.snippetProps })}
+				{:else}
+					<div {...contentProps}>
+						{@render children?.()}
+					</div>
+				{/if}
+			</div>
+		{/snippet}
+	</SelectItemAlignedContent>
+{:else if forceMount}
 	<PopperLayerForceMount
 		{...mergedProps}
 		{...contentState.popperProps}

packages/bits-ui/src/lib/bits/select/components/select-content.svelte

@@ -6,6 +6,7 @@
 	import { noop } from "$lib/internal/noop.js";
 	import PopperLayerForceMount from "$lib/bits/utilities/popper-layer/popper-layer-force-mount.svelte";
 	import { createId } from "$lib/internal/create-id.js";
+	import SelectItemAlignedContent from "./select-item-aligned-content.svelte";
 
 	const uid = $props.id();
 
@@ -20,6 +21,7 @@
 		child,
 		preventScroll = false,
 		style,
+		position = "popper",
 		...restProps
 	}: SelectContentProps = $props();
 
@@ -31,12 +33,52 @@
 		),
 		onInteractOutside: boxWith(() => onInteractOutside),
 		onEscapeKeydown: boxWith(() => onEscapeKeydown),
+		position: boxWith(() => position),
 	});
 
 	const mergedProps = $derived(mergeProps(restProps, contentState.props));
+
+	// Svelte action to register the fixed wrapper node. Using use: instead of ref={fn}
+	// because the callback ref syntax doesn't trigger in this Svelte version.
+	function mountWrapper(node: HTMLElement) {
+		contentState.setContentWrapper(node);
+		return { destroy: () => contentState.setContentWrapper(null) };
+	}
 </script>
 
-{#if forceMount}
+{#if contentState.useItemAligned}
+	<SelectItemAlignedContent
+		{id}
+		ref={contentState.opts.ref}
+		enabled={contentState.root.opts.open.current}
+		shouldRender={contentState.shouldRender}
+		{preventScroll}
+		onEscapeKeydown={contentState.onEscapeKeydown}
+		onInteractOutside={contentState.onInteractOutside}
+		onOpenAutoFocus={contentState.onOpenAutoFocus}
+		onCloseAutoFocus={contentState.onCloseAutoFocus}
+		trapFocus={false}
+		loop={false}
+	>
+		{#snippet content({ props: layerProps })}
+			{@const contentProps = mergeProps(restProps, layerProps, contentState.props, { style })}
+			<!-- Radix-style two-div structure: fixed wrapper + content div that fills it -->
+			<div use:mountWrapper data-select-content-wrapper style="position: fixed; display: flex; flex-direction: column;">
+				{#if child}
+					{@render child({
+						props: contentProps,
+						wrapperProps: {},
+						...contentState.snippetProps,
+					})}
+				{:else}
+					<div {...contentProps}>
+						{@render children?.()}
+					</div>
+				{/if}
+			</div>
+		{/snippet}
+	</SelectItemAlignedContent>
+{:else if forceMount}
 	<PopperLayerForceMount
 		{...mergedProps}
 		{...contentState.popperProps}