facebook / facebook/astryx

Selector: open the menu underneath the trigger (reconsider overlay-over-trigger default)

Open
#4,227 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
13.1k
Forks
1.1k
Avg merge
1d 14h
Merged PRs (30d)
669

Description

## Summary

`Selector`'s menu currently **overlays the trigger** by default — the selected item is positioned *over* the button (native ``-like behavior), so the open menu covers the button. For the migration use case (and arguably in general) it would read better to have the menu open **underneath the button** instead of on top of it.

## The capability already exists

This is not a missing feature. `Selector` already accepts a `placement` prop (`LayerPlacement = 'above' | 'below' | 'start' | 'end'`):

- **Omitted (today's default):** selector-specific overlay behavior — the selected item is positioned over the trigger and clamped to the viewport (menu covers the button).
- **`placement="below"`:** opts out of the overlay and uses standard layer positioning — the menu opens directly beneath the trigger (the desired "underneath the button" behavior).

So consumers can already get the under-the-button behavior today with ``.

## Proposal / question

Should **`placement="below"` (open underneath) become the default** for `Selector`, replacing the current overlay-selected-item-over-trigger default?

- **For:** matches the common dropdown mental model, avoids the menu obscuring the trigger, and is what the migration target expects. Lower surprise for most consumers.
- **Against / to consider:** the overlay behavior is a deliberate native-select affordance (keeps the selected item under the pointer); changing the default is a **visual behavior change** for every existing `Selector` that doesn't set `placement`. Needs the API-conventions view on whether to (a) flip the default, (b) keep the overlay default but document `placement="below"` more prominently, or (c) introduce a semantic default that resolves to below.

This is a **design / default-behavior decision**, not a bug — the mechanism is in place; the question is what the default should be and how to migrate it non-disruptively.

## Acceptance

- A decision on the default placement (flip to `below` vs keep overlay + document), with migration considerations if the default changes.
- If flipped: a changeset noting the visual behavior change, and confirmation that `placement` still lets consumers opt back into the overlay behavior.

Contributor guide

Open the contributing guide

Research direction

Start with the Selector entry point and trace how its placement prop chooses between the current overlay behavior and standard layer positioning. Review the API-conventions implications of changing the default, then document the decision and migration path; if the default changes, add a changeset and confirm placement still provides the overlay behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
design, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.