feat(PinInput): expose inputRef bindable prop (#2028)

Author: huntabyte

.changeset/plenty-ears-grin.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+feat(PinInput): add bindable `inputRef` on `PinInput.Root`

docs/src/lib/content/api-reference/pin-input.api.ts

@@ -18,6 +18,7 @@ import {
 	defineNumberProp,
 	defineObjectProp,
 	defineSimpleDataAttr,
+	defineSimplePropSchema,
 	defineStringProp,
 } from "../utils.js";
 
@@ -63,6 +64,13 @@ const root = defineComponentApiSchema<PinInputRootPropsWithoutHTML>({
 		inputId: defineStringProp({
 			description: "Optionally provide an ID to apply to the hidden input element.",
 		}),
+		inputRef: defineSimplePropSchema({
+			type: "HTMLInputElement",
+			description:
+				"The hidden `<input>` element that holds the OTP value. Bind to this to call `focus()`, read the selection, etc.",
+			bindable: true,
+			default: "null",
+		}),
 		pushPasswordManagerStrategy: defineEnumProp({
 			description:
 				"Enabled by default, it's an optional strategy for detecting Password Managers in the page and then shifting their badges to the right side, outside the input.",

package.json

@@ -70,9 +70,9 @@
       "@tailwindcss/vite": "^4.1.13",
       "@types/node": "^20.19.16",
       "playwright": "1.55.0",
-      "runed": "^0.35.1",
-      "svelte": "5.46.4",
-      "svelte-check": "^4.3.1",
+      "runed": "0.37.1",
+      "svelte": "5.55.4",
+      "svelte-check": "^4.4.6",
       "tailwindcss": "^4.1.13",
       "typescript": "^5.9.2",
       "vite": "^7.1.5",

packages/bits-ui/src/lib/bits/pin-input/components/pin-input.svelte

@@ -11,6 +11,7 @@
 		id = createId(uid),
 		inputId = `${createId(uid)}-input`,
 		ref = $bindable(null),
+		inputRef = $bindable(null),
 		maxlength = 6,
 		textalign = "left",
 		pattern,
@@ -33,6 +34,10 @@
 			() => ref,
 			(v) => (ref = v)
 		),
+		inputRef: boxWith(
+			() => inputRef,
+			(v) => (inputRef = v)
+		),
 		inputId: boxWith(() => inputId),
 		autocomplete: boxWith(() => autocomplete),
 		maxLength: boxWith(() => maxlength),

packages/bits-ui/src/lib/bits/pin-input/pin-input.svelte.ts

@@ -34,6 +34,7 @@ interface PinInputRootStateOpts
 	extends WithRefOpts,
 		WritableBoxedValues<{
 			value: string;
+			inputRef: HTMLInputElement | null;
 		}>,
 		ReadableBoxedValues<{
 			inputId: string;
@@ -83,9 +84,8 @@ export class PinInputRootState {
 
 	readonly opts: PinInputRootStateOpts;
 	readonly attachment: RefAttachment;
-	#inputRef = simpleBox<HTMLInputElement | null>(null);
+	readonly inputAttachment: RefAttachment<HTMLInputElement>;
 	#isHoveringInput = $state(false);
-	readonly inputAttachment: RefAttachment<HTMLInputElement> = attachRef(this.#inputRef);
 	#isFocused = simpleBox(false);
 	#mirrorSelectionStart = $state<number | null>(null);
 	#mirrorSelectionEnd = $state<number | null>(null);
@@ -110,6 +110,7 @@ export class PinInputRootState {
 	constructor(opts: PinInputRootStateOpts) {
 		this.opts = opts;
 		this.attachment = attachRef(this.opts.ref);
+		this.inputAttachment = attachRef(this.opts.inputRef);
 		this.domContext = new DOMContext(opts.ref);
 
 		this.#initialLoad = {
@@ -121,14 +122,14 @@ export class PinInputRootState {
 
 		this.#pwmb = usePasswordManagerBadge({
 			containerRef: this.opts.ref,
-			inputRef: this.#inputRef,
+			inputRef: this.opts.inputRef,
 			isFocused: this.#isFocused,
 			pushPasswordManagerStrategy: this.opts.pushPasswordManagerStrategy,
 			domContext: this.domContext,
 		});
 
 		onMount(() => {
-			const input = this.#inputRef.current;
+			const input = this.opts.inputRef.current;
 			const container = this.opts.ref.current;
 
 			if (!input || !container) return;
@@ -180,9 +181,9 @@ export class PinInputRootState {
 			};
 		});
 
-		watch([() => this.opts.value.current, () => this.#inputRef.current], () => {
+		watch([() => this.opts.value.current, () => this.opts.inputRef.current], () => {
 			syncTimeouts(() => {
-				const input = this.#inputRef.current;
+				const input = this.opts.inputRef.current;
 				if (!input) return;
 				// forcefully remove :autofill state
 				input.dispatchEvent(new Event("input"));
@@ -313,7 +314,7 @@ export class PinInputRootState {
 	}
 
 	#onDocumentSelectionChange = () => {
-		const input = this.#inputRef.current;
+		const input = this.opts.inputRef.current;
 		const container = this.opts.ref.current;
 		if (!input || !container) return;
 
@@ -363,7 +364,7 @@ export class PinInputRootState {
 			}
 
 			if (start !== -1 && end !== -1 && start !== end) {
-				this.#inputRef.current?.setSelectionRange(start, end, direction);
+				this.opts.inputRef.current?.setSelectionRange(start, end, direction);
 			}
 		}
 
@@ -398,7 +399,7 @@ export class PinInputRootState {
 	};
 
 	onfocus = (_: BitsFocusEvent<HTMLInputElement>) => {
-		const input = this.#inputRef.current;
+		const input = this.opts.inputRef.current;
 		if (input) {
 			const start = Math.min(input.value.length, this.opts.maxLength.current - 1);
 			const end = input.value.length;
@@ -410,7 +411,7 @@ export class PinInputRootState {
 	};
 
 	onpaste = (e: BitsEvent<ClipboardEvent>) => {
-		const input = this.#inputRef.current;
+		const input = this.opts.inputRef.current;
 		if (!input) return;
 
 		const getNewValue = (finalContent: string | undefined) => {

packages/bits-ui/src/lib/bits/pin-input/types.ts

@@ -69,6 +69,13 @@ export type PinInputRootPropsWithoutHTML = Omit<
 			 */
 			inputId?: string;
 
+			/**
+			 * The underlying hidden `<input>` element. Bind to call `focus()`, read selection, etc.
+			 *
+			 * @bindable
+			 */
+			inputRef?: HTMLInputElement | null;
+
 			/**
 			 * The children snippet used to render the individual cells.
 			 */

tests/src/tests/pin-input/pin-input-test.svelte

@@ -11,6 +11,8 @@
 		toCopy?: string;
 	} = $props();
 
+	let inputRef = $state<HTMLInputElement | null>(null);
+
 	type CellProps = PinInputRootSnippetProps["cells"][0];
 </script>
 
@@ -19,9 +21,14 @@
 		{value}
 	</button>
 
+	<button type="button" data-testid="focus-input" onclick={() => inputRef?.focus()}>
+		focus input
+	</button>
+
 	<PinInput.Root
 		aria-label="my input"
 		inputId="myInput"
+		bind:inputRef
 		bind:value
 		class="group/pininput text-foreground flex items-center has-[:disabled]:opacity-30"
 		{maxlength}

tests/src/tests/pin-input/pin-input.browser.test.ts

@@ -36,6 +36,12 @@ afterEach(() => {
 	vi.resetAllMocks();
 });
 
+it("should focus the hidden input when `inputRef.focus()` is called", async () => {
+	const t = setup();
+	await t.getByTestId("focus-input").click();
+	await expect.element(t.hiddenInput).toHaveFocus();
+});
+
 it("should sync the `name` prop to the hidden input", async () => {
 	const t = setup({ name: "test" });
 	await expect.element(t.hiddenInput).toHaveAttribute("name", "test");