feat(prompts,core): make autocomplete placeholder tabbable (#485)

dreyfus92 · natemoo-re · web-flow · commit bdf89a5f80b9 · 2026-03-16T16:41:03.000-05:00
Co-authored-by: Nate Moore &lt;natemoo-re@users.noreply.github.com&gt;
diff --git a/.changeset/dirty-actors-find.md b/.changeset/dirty-actors-find.md
@@ -0,0 +1,7 @@
+---
+"@clack/prompts": patch
+"@clack/core": patch
+---
+
+Adds `placeholder` option to `autocomplete`. When the placeholder is set and the input is empty, pressing `tab` will set the value to `placeholder`.
+
diff --git a/packages/core/src/prompts/autocomplete.ts b/packages/core/src/prompts/autocomplete.ts
@@ -51,6 +51,13 @@ export interface AutocompleteOptions<T extends OptionLike>
 	options: T[] | ((this: AutocompletePrompt<T>) => T[]);
 	filter?: FilterFunction<T>;
 	multiple?: boolean;
+	/**
+	 * When set (non-empty), pressing Tab with no input fills the field with this value
+	 * and runs the normal filter/selection logic so the user can confirm with Enter.
+	 * Tab only fills the input when the placeholder matches at least one option under
+	 * the prompt's filter (so the value remains selectable).
+	 */
+	placeholder?: string;
 }
 
 export default class AutocompletePrompt<T extends OptionLike> extends Prompt<
@@ -66,6 +73,7 @@ export default class AutocompletePrompt<T extends OptionLike> extends Prompt<
 	#lastUserInput = '';
 	#filterFn: FilterFunction<T>;
 	#options: T[] | (() => T[]);
+	#placeholder: string | undefined;
 
 	get cursor(): number {
 		return this.#cursor;
@@ -94,6 +102,7 @@ export default class AutocompletePrompt<T extends OptionLike> extends Prompt<
 		super(opts);
 
 		this.#options = opts.options;
+		this.#placeholder = opts.placeholder;
 		const options = this.options;
 		this.filteredOptions = [...options];
 		this.multiple = opts.multiple === true;
@@ -143,6 +152,24 @@ export default class AutocompletePrompt<T extends OptionLike> extends Prompt<
 		const isDownKey = key.name === 'down';
 		const isReturnKey = key.name === 'return';
 
+		// Tab with empty input and placeholder: fill input with placeholder to trigger autocomplete
+		// Only when the placeholder matches at least one (non-disabled) option so the value remains selectable
+		const isEmptyOrOnlyTab = this.userInput === '' || this.userInput === '\t';
+		const placeholder = this.#placeholder;
+		const options = this.options;
+		const placeholderMatchesOption =
+			placeholder !== undefined &&
+			placeholder !== '' &&
+			options.some((opt) => !opt.disabled && this.#filterFn(placeholder, opt));
+		if (key.name === 'tab' && isEmptyOrOnlyTab && placeholderMatchesOption) {
+			if (this.userInput === '\t') {
+				this._clearUserInput();
+			}
+			this._setUserInput(placeholder, true);
+			this.isNavigating = false;
+			return;
+		}
+
 		// Start navigation mode with up/down arrows
 		if (isUpKey || isDownKey) {
 			this.#cursor = findCursor(this.#cursor, isUpKey ? -1 : 1, this.filteredOptions);
diff --git a/packages/core/test/prompts/autocomplete.test.ts b/packages/core/test/prompts/autocomplete.test.ts
@@ -197,4 +197,38 @@ describe('AutocompletePrompt', () => {
 		expect(instance.selectedValues).to.deep.equal([]);
 		expect(result).to.deep.equal([]);
 	});
+
+	test('Tab with empty input and placeholder fills input and submit returns matching option', async () => {
+		const instance = new AutocompletePrompt({
+			input,
+			output,
+			render: () => 'foo',
+			options: testOptions,
+			placeholder: 'apple',
+		});
+
+		const promise = instance.prompt();
+		input.emit('keypress', '\t', { name: 'tab' });
+		input.emit('keypress', '', { name: 'return' });
+		const result = await promise;
+
+		expect(instance.userInput).to.equal('apple');
+		expect(result).to.equal('apple');
+	});
+
+	test('Tab with non-matching placeholder does not fill input', async () => {
+		const instance = new AutocompletePrompt({
+			input,
+			output,
+			render: () => 'foo',
+			options: testOptions,
+			placeholder: 'Type to search...',
+		});
+
+		instance.prompt();
+		input.emit('keypress', '\t', { name: 'tab' });
+
+		// Placeholder does not match any option, so input must not be filled with placeholder
+		expect(instance.userInput).not.to.equal('Type to search...');
+	});
 });
diff --git a/packages/prompts/src/autocomplete.ts b/packages/prompts/src/autocomplete.ts
@@ -85,6 +85,7 @@ export const autocomplete = <Value>(opts: AutocompleteOptions<Value>) => {
 		options: opts.options,
 		initialValue: opts.initialValue ? [opts.initialValue] : undefined,
 		initialUserInput: opts.initialUserInput,
+		placeholder: opts.placeholder,
 		filter:
 			opts.filter ??
 			((search: string, opt: Option<Value>) => {
@@ -267,6 +268,7 @@ export const autocompleteMultiselect = <Value>(opts: AutocompleteMultiSelectOpti
 	const prompt = new AutocompletePrompt<Option<Value>>({
 		options: opts.options,
 		multiple: true,
+		placeholder: opts.placeholder,
 		filter:
 			opts.filter ??
 			((search, opt) => {
diff --git a/packages/prompts/test/autocomplete.test.ts b/packages/prompts/test/autocomplete.test.ts
@@ -137,6 +137,37 @@ describe('autocomplete', () => {
 		expect(value).toBe('apple');
 	});
 
+	test('Tab with placeholder fills input and Enter submits matching option', async () => {
+		const result = autocomplete({
+			message: 'Select a fruit',
+			placeholder: 'apple',
+			options: testOptions,
+			input,
+			output,
+		});
+
+		input.emit('keypress', '\t', { name: 'tab' });
+		input.emit('keypress', '', { name: 'return' });
+		const value = await result;
+		expect(value).toBe('apple');
+	});
+
+	test('Tab with non-matching placeholder does not fill input', async () => {
+		const result = autocomplete({
+			message: 'Select a fruit',
+			placeholder: 'Type to search...',
+			options: testOptions,
+			input,
+			output,
+		});
+
+		input.emit('keypress', '\t', { name: 'tab' });
+		input.emit('keypress', '', { name: 'return' });
+		const value = await result;
+		// Tab did not fill input with placeholder (no option matches), so Enter submits first option
+		expect(value).toBe('apple');
+	});
+
 	test('supports initialValue', async () => {
 		const result = autocomplete({
 			message: 'Select a fruit',
@@ -410,6 +441,21 @@ describe('autocompleteMultiselect', () => {
 		expect(value).toEqual([]);
 		expect(output.buffer).toMatchSnapshot();
 	});
+
+	test('Tab with placeholder fills input; Enter submits current selection', async () => {
+		const result = autocompleteMultiselect({
+			message: 'Select fruits',
+			placeholder: 'apple',
+			options: testOptions,
+			input,
+			output,
+		});
+
+		input.emit('keypress', '\t', { name: 'tab' });
+		input.emit('keypress', '', { name: 'return' });
+		const value = await result;
+		expect(value).toEqual([]);
+	});
 });
 
 describe('autocomplete with custom filter', () => {
