You wrote a CSS rule for the dropdown list of a PrimeFaces <p:selectOneMenu> and the browser simply ignores it. Or the list is wider than the menu itself. Or the menu keeps its focus border after you picked an item with the mouse. Most of these have the same cause: on the client side the component is not one piece of HTML but two, and the second piece does not live where you think. This guide walks through the markup, the classes, and the CSS for the most common styling wishes.
All examples are verified against PrimeFaces 16.0.2 with the default Saga theme.
Two pieces of HTML in DOM
A <p:selectOneMenu> renders a dropdown box:
<p:selectOneMenu id="country" value="#{bean.country}">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>

And an overlay panel with the options:

The generated HTML has the panel's markup inside the box's markup.
<div id="form:menu" class="ui-selectonemenu ui-widget ui-state-default">
<div class="ui-helper-hidden-accessible">
<select id="form:menu_input" name="form:menu_input" tabindex="-1" autocomplete="off" aria-hidden="true">
<option value="" selected="selected" data-escape="true">Select a country</option>
<option value="CW" data-escape="true">CuraƧao</option>
<option value="NL" data-escape="true">Netherlands</option>
...
</select>
</div>
<span id="form:menu_label" class="ui-selectonemenu-label ui-inputfield" tabindex="0" aria-controls="form:menu_panel" role="combobox" aria-haspopup="listbox" aria-expanded="false"> </span>
<div class="ui-selectonemenu-trigger ui-state-default">
<span class="ui-icon ui-icon-triangle-1-s ui-c"></span>
</div>
<div id="form:menu_panel" class="ui-selectonemenu-panel ui-widget ui-widget-content ui-helper-hidden ui-shadow ui-input-overlay" tabindex="-1">
<div class="ui-selectonemenu-filter-container">
<input class="ui-selectonemenu-filter ui-inputfield ui-inputtext ui-widget ui-state-default" id="form:menu_filter" name="form:menu_filter" type="text" autocomplete="off" aria-controls="form:menu_table" />
<span class="ui-icon ui-icon-search"></span>
</div>
<div class="ui-selectonemenu-items-wrapper" style="max-height:200px"></div>
</div>
</div>
<script id="form:menu_s">$(function(){PrimeFaces.cw("SelectOneMenu","widget_form_menu",{id:"form:menu",appendTo:"@(body)",renderPanelContentOnClient:true,filter:true,filterMatchMode:"contains"});});</script>
The panel arrives with an empty items wrapper: the widget script builds the items from the options of the hidden <select> the first time the panel opens.
But the appendTo attribute defaults to @(body), so the widget script moves the panel to the end of <body> during page load. This way no parent with overflow: hidden or overflow: auto can clip the open panel, see "What appendTo actually does". Its ID is the menu ID with an _panel suffix. Below is the tree of what ends up in the DOM for <p:selectOneMenu id="menu" filter="true"> in <h:form id="form">.
div#form:menu.ui-selectonemenu.ui-widget.ui-state-default
├── div.ui-helper-hidden-accessible
│ └── select#form:menu_input
├── span#form:menu_label.ui-selectonemenu-label.ui-inputfield
└── div.ui-selectonemenu-trigger.ui-state-default
└── span.ui-icon.ui-icon-triangle-1-s
body
└── div#form:menu_panel.ui-selectonemenu-panel.ui-widget.ui-widget-content.ui-shadow.ui-input-overlay
├── div.ui-selectonemenu-filter-container (only with filter="true")
│ └── input.ui-selectonemenu-filter
├── div.ui-selectonemenu-items-wrapper
│ └── div.ui-selectonemenu-items
│ └── ul.ui-selectonemenu-list
│ ├── li.ui-selectonemenu-item-group (only with grouped select items)
│ └── li.ui-selectonemenu-item.ui-selectonemenu-list-item
└── div.ui-selectonemenu-footer (only with a footer facet)
Hence, two pieces of HTML in DOM. One for the box and another for the panel.
The real <select> is visually hidden. It only holds the submitted value. The keyboard focus goes to the <span class="ui-selectonemenu-label">. With editable="true" that <span> is an <input class="ui-selectonemenu-label"> instead.
Styling the box
The box is the root div, with the label and the trigger inside. Give it a class of your own via styleClass, and add that class to the theme selectors.
To find a theme selector, right-click the box in the browser and choose Inspect. The developer tools open with the element under the mouse selected, usually the label. Click its parent div.ui-selectonemenu in the element tree to get to the root. The Styles pane lists every CSS rule which applies to that element, with the winning one on top and the overridden properties struck through. Firefox calls these the Inspector and the Rules pane. Copy the selector of the theme rule you want to override, and add your class to it.
For example a pill shaped box with a light gray background in place of a border, a bold label and a trigger icon in the primary color.
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="country-menu">
body .ui-selectonemenu.country-menu {
border-color: transparent;
border-radius: 2rem;
background: var(--surface-c);
}
body .ui-selectonemenu.country-menu .ui-selectonemenu-label {
padding-left: 1rem;
font-weight: 600;
}
body .ui-selectonemenu.country-menu .ui-selectonemenu-trigger .ui-icon {
color: var(--primary-color);
}
Now the box is a gray pill:

The transparent border also wins over the blue border of the hover and focus states: the selector has the same specificity as the default theme's, and your stylesheet comes after it. So give those states their border color back.
body .ui-selectonemenu.country-menu.ui-state-hover,
body .ui-selectonemenu.country-menu.ui-state-focus {
border-color: var(--primary-color);
}
The focus shadow of the default theme stays. The next section shows all state classes to hook into.
The state classes
The widget script toggles a handful of state classes. These are the ones you can hook into.
| Class | Set on | When |
|---|---|---|
ui-state-hover | root and trigger | mouse is over the box, but only while it does not have focus |
ui-state-focus | root and trigger | the label has keyboard focus |
ui-state-error | root and trigger | the component is invalid after validation |
ui-state-disabled | root, or individual items | disabled="true" on the menu or on a <f:selectItem> |
ui-state-readonly | root | readonly="true" |
ui-state-hover | item | mouse is over the item |
ui-state-highlight | item | the item is the currently selected one |
ui-inputwrapper-focus | root | the label has focus, only inside .ui-float-label |
ui-inputwrapper-filled | root | the menu has a value, only inside .ui-float-label, but see "The floating label" |
Note that there is no ui-selectonemenu-open, no ui-selectonemenu-focus and no p-focus class. That last one is from PrimeNG, PrimeReact and PrimeVue. The focus state is represented by ui-state-focus on the root. The default theme draws the blue border and the light blue box shadow with it. The open state is not a class at all. It is reflected by aria-expanded="true" on the label, see further below.
You can for example replace the soft shadow by a crisp ring, with a white gap between the box and the ring.
body .ui-selectonemenu.ui-state-focus {
border-color: var(--p-primary-700);
box-shadow: 0 0 0 2px var(--surface-a), 0 0 0 4px var(--p-primary-700);
}
This selector equals the default theme's, and your stylesheet comes after it, so it wins. Now the focused menu gets a dark blue ring:

The same ring stays after a mouse selection, see "The focus which stays" for that.
The required and invalid state
A required="true" menu gets no class of its own. Only its label gets aria-required="true", so :has() on that attribute can mark the box, for example with a thicker left border.
body .ui-selectonemenu:not(.ui-state-error):has(> .ui-selectonemenu-label[aria-required="true"]) {
border-left: 3px solid var(--primary-color);
}
The :not(.ui-state-error) keeps the red border of the error state intact. Now a required menu stands out:

A required="true" menu which is submitted without a selection gets ui-state-error:
<h:form id="form">
<p:selectOneMenu id="country" value="#{bean.country}" required="true" requiredMessage="Please select a country">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
<p:message for="country" />
<p:commandButton id="submit" value="Submit" process="@form" update="@form" />
</h:form>

It keeps its red border while it is open:

The default theme only colors the border of ui-state-error. You can for example add a light red background and a red trigger icon. The label also gets aria-invalid="true", in case you prefer to hook into that.
The default theme has unfortunately no custom property for the error color. #f44336 is the one of Saga, so define it yourself.
:root {
--error-color: #f44336;
}
body .ui-selectonemenu.ui-state-error {
background: var(--p-red-50);
}
body .ui-selectonemenu.ui-state-error .ui-selectonemenu-trigger .ui-icon {
color: var(--error-color);
}
Now the error stands out more:

The disabled state
A disabled="true" menu is grayed out and does not open:
<p:selectOneMenu id="country" value="#{bean.country}" disabled="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>

The default theme fades the whole box with body .ui-state-disabled { opacity: .6; }. A gray background with a muted label is an alternative.
body .ui-selectonemenu.ui-state-disabled {
opacity: 1;
background: var(--surface-c);
}
body .ui-selectonemenu.ui-state-disabled .ui-selectonemenu-label {
color: var(--text-color-secondary);
}
Now it is gray instead of faded:

The readonly state
A readonly="true" menu looks like a normal one, and it still opens its panel on click:
<p:selectOneMenu id="country" value="#{bean.country}" readonly="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>

The default theme does not style ui-state-readonly at all. A slight opacity tells it apart, and pointer-events: none stops the mouse from opening it.
body .ui-selectonemenu.ui-state-readonly {
opacity: .8;
pointer-events: none;
}
Now it looks slightly faded:

The keyboard can still open it with Space, and the arrow keys still change the shown value. That is only on the screen: PrimeFaces does not decode a readonly menu, so the server ignores that value.
The floating label
Put the menu in a .ui-float-label, with the label after it. The label must come after the menu in the XHTML. The default theme floats it with the sibling selector .ui-inputwrapper-focus ~ label, which only matches a label that follows the menu. A label before the menu never floats. The placeholder item gets an empty label, so that the box stays empty and the floating label can take its place.
<span class="ui-float-label">
<p:selectOneMenu id="country" value="#{bean.country}">
<f:selectItem itemValue="#{null}" itemLabel="" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
<p:outputLabel for="country" value="Country" />
</span>
Without focus and without value, the label sits in the box:

While the menu has focus, the root gets ui-inputwrapper-focus and the label floats above the box:

While it has a value, the root should get ui-inputwrapper-filled, so that the label stays up there. It never gets it. Select a country and click somewhere else: the label drops back onto the value (#15495).
The hidden <select> still knows its value, so CSS can float the label on its own. The placeholder <option> has an empty value, every other one has not.
body .ui-float-label > .ui-selectonemenu:has(select option:checked:not([value=""])) ~ label {
top: -.75em;
font-size: 12px;
}
Now the label stays above the selected value:

Also while the panel is open:

The label is a sibling after the root, so .ui-inputwrapper-focus ~ label styles it while the menu has the focus, for example in the primary color of the default theme.
body .ui-float-label > .ui-inputwrapper-focus ~ label {
color: var(--primary-color);
}
Without the focus the label keeps the muted color of the default theme, with the focus it gets the primary color:

The empty placeholder item does give an empty first line in the panel, as you could see above. It renders as <li data-value="">, so a ::before can give it a text of its own, in the panel only.
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-item[data-value=""]::before {
content: "No country";
}
Now the first line reads "No country", while the box stays empty:

Styling the panel
When styling the panel, you'd expect to be able to select it through the <p:selectOneMenu>, like this:
body .ui-selectonemenu .ui-selectonemenu-panel .ui-selectonemenu-item {
font-style: italic;
color: crimson;
}
But the panel is not a descendant of the box anymore. It is a child of <body>. So the items stay unstyled:

Before going on, note the right corners of that panel. The scrollbar of the .ui-selectonemenu-items-wrapper fills them, so those corners look square, on contrary to the left corners:

An overflow: hidden on the panel clips its content to its rounded corners. All panels further below have this rule.
body .ui-selectonemenu-panel {
overflow: hidden;
}
Now the corner is round:

Now back to the styling of specific panels. Use the panelStyleClass attribute. It puts your own class on the panel itself, wherever it ends up.
<p:selectOneMenu id="country" value="#{bean.country}" panelStyleClass="country-panel">
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
Then mind the specificity. The default theme styles the items with body .ui-selectonemenu-panel .ui-selectonemenu-items .ui-selectonemenu-item. A shorter selector only wins for properties the default theme does not set itself, such as font-style. For a color it loses.
body .country-panel .ui-selectonemenu-item {
font-style: italic;
color: crimson;
}
The items get italic, but not red:

Simply repeat the theme selector and add your class to it. Find it in the developer tools, the same way as for the box. If the panel closes when the developer tools take the focus, the items are still in the element tree: the panel stays in the DOM after it has been opened once, only hidden.
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items .ui-selectonemenu-item {
font-style: italic;
color: crimson;
}
Now the items are italic and red:

For the height of the list, do not fight with CSS. The height attribute is rendered as an inline max-height on the .ui-selectonemenu-items-wrapper, with a default of 200px. A max-height in your CSS file loses against that.
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items-wrapper {
max-height: 8em;
}
The list stays 200px high:

So just set the height attribute on the component.
<p:selectOneMenu id="country" value="#{bean.country}" height="100">
Now the list is 100px high:

The attribute takes any CSS length, so height="10em" works as well.
An !important on that max-height in your CSS file would win over the inline style. But then the height attribute silently stops working for every menu that the rule matches. And a menu which needs yet another height needs an !important of its own.
Option groups
Each group of an <f:selectItemGroups> ends up as a li.ui-selectonemenu-item-group above its items:
<p:selectOneMenu id="country" value="#{bean.country}">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItemGroups value="#{bean.continents}" var="continent" itemLabel="#{continent.name}">
<f:selectItems value="#{continent.countries}" var="country" itemLabel="#{country.name}" itemValue="#{country.code}" />
</f:selectItemGroups>
</p:selectOneMenu>

Style the group headers the same way as the items in the previous section: via the panelStyleClass, with the theme selector repeated. For example a smaller uppercase font on a light background, so that they stand apart from the items.
<p:selectOneMenu id="country" value="#{bean.country}" panelStyleClass="country-panel">
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items .ui-selectonemenu-item-group {
padding: .5rem 1rem;
font-size: .75rem;
letter-spacing: .05em;
text-transform: uppercase;
background: var(--surface-b);
}
Now the group headers stand apart from the items:

Filterable panel
With filter="true" the panel gets the filter field above the items:
<p:selectOneMenu id="country" value="#{bean.country}" filter="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>

That is helpful when you have a lot of items. But with over a hundred items, a <p:autoComplete> is probably the better choice.
The default theme puts the search icon on the left side of the filter field. To move it to the right side, swap the left of the icon for a right. Also swap the left padding of the field for a right padding, so that the typed text does not run under the icon.
<p:selectOneMenu id="country" value="#{bean.country}" filter="true" panelStyleClass="country-panel">
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-filter-container .ui-selectonemenu-filter.ui-inputfield {
padding-left: .5rem;
padding-right: 2rem;
}
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-filter-container .ui-icon {
left: auto;
right: 1.5rem;
}
Now the search icon sits on the right side:

Hiding items on a condition
Sometimes you want to hide some items depending on a condition, for example everything outside Europe when a checkbox is ticked. You do not need to rebuild the list behind <f:selectItems> for every condition. Let itemDisabled decide which items apply:
<p:selectOneMenu id="country" value="#{bean.country}" panelStyleClass="country-panel">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" var="country" itemLabel="#{country.name}" itemValue="#{country.code}"
itemDisabled="#{bean.europeOnly and country.continent ne 'Europe'}" />
</p:selectOneMenu>
<p:selectBooleanCheckbox id="europeOnly" value="#{bean.europeOnly}" itemLabel="Europe only">
<p:ajax update="country" />
</p:selectBooleanCheckbox>
A disabled item gets the ui-state-disabled class in the panel, so CSS can simply hide it:
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items .ui-selectonemenu-item.ui-state-disabled {
display: none;
}
Without the checkbox all countries are there:

With the checkbox only the European ones are left:

The arrow keys skip the hidden items as well.
Do note that PrimeFaces 16.0.2 still accepts the value of a disabled item when someone submits it anyway with a manipulated request, whereas <h:selectOneMenu> silently ignores it. PrimeFaces used to reject such a request with an exception. Since 15.0.8 and 16.0.0 it is supposed to ignore the value silently, but it lets the value through instead (#13954). Until that is fixed, validate the value in the bean if it matters.
Width of the box and the panel
By default the box gets an inline min-width equal to the width of the hidden <select>, which the browser makes as wide as its longest option. This is the autoWidth attribute at work. The panel is at least as wide as the box, but it grows with its widest item. Items have more padding than the native <select> options, and the width of the panel includes the vertical scrollbar of a long list. So out of the box the panel is a few pixels wider than the box:

Inside a .ui-fluid parent autoWidth does nothing, and the box takes the full width of its parent instead:
<h:form id="form" styleClass="ui-fluid">
<p:selectOneMenu id="country" value="#{bean.country}">
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
</h:form>

When you want a fixed width, a width in CSS is not enough.
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="narrow">
body .ui-selectonemenu.narrow {
width: 12em;
}
The inline min-width still wins:

Set autoWidth="false" as well.
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="narrow" autoWidth="false">
Now the box is 12em. A long selected label is hard cut, and it runs on under the trigger. The panel is still as wide as its widest item:

The label clips without ellipsis by default. Add one.
body .ui-selectonemenu.narrow .ui-selectonemenu-label {
text-overflow: ellipsis;
}
The ellipsis stops before the trigger:

For the panel you have two choices once you cap its width with a max-width. It works against the inline width the widget script sets, because a max-width always wins over a width.
The first choice is an ellipsis on the items. Combine it with an itemDescription holding the full label, so that it shows up as tooltip on the item.
body .ui-selectonemenu-panel.country-panel {
max-width: 12em;
}
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items .ui-selectonemenu-item {
overflow: hidden;
text-overflow: ellipsis;
}
The long items get an ellipsis:

The second choice is wrapping the long items over multiple lines.
body .ui-selectonemenu-panel.country-panel {
max-width: 12em;
}
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-items .ui-selectonemenu-item {
white-space: normal;
}
The long items wrap:

The 12em simply repeats the width of the box. A percentage does not work here: it refers to the parent, and the parent of the panel in the body is <body>, not the box.
When using appendTo="@this", the panel is a child of the box, so max-width: 100% refers to the box instead. That 100% is the inside of the box, without its borders. So it needs the two 1px borders of the box added, and the panel needs to shift 1px to the left.
body .ui-selectonemenu-panel.country-panel {
max-width: calc(100% + 2px);
margin-left: -1px;
}
Now the box and the panel are exactly equally wide:

Do note the side effects of appendTo="@this", described in the next section.
What appendTo actually does
With the default @(body), the panel escapes every parent with overflow: hidden or overflow: auto. It gets a fresh z-index each time it opens, and it is positioned right below the box. When there is no room below, it flips above the box, see "Merging the box and the panel".
Here the panel in the body escapes the dashed box with overflow: hidden:

With appendTo="@this" the panel stays inside the root div. Your parent scoped CSS works again, and the panel never flips. But now any parent with overflow: hidden or overflow: auto clips the panel:

A menu in a fixed height card or in a table cell then shows a cut-off list. The appendTo attribute takes any search expression, so @form or @(.some-container) works as well. Pick the closest parent which is not clipped.
Scrolling is not affected by appendTo. In both cases the widget closes the panel as soon as the page or a parent of the menu scrolls. Here a dashed box which scrolls, with the panel in the body:

And with the panel in @this, with the scrollbar of the dashed box marked:

If you want it to stay open and follow the box instead, then set this once in a global script.
PrimeFaces.hideOverlaysOnViewportChange = false;
Inside a <p:dialog>, which has position: fixed, the panel gets position: fixed as well, so it stays aligned with the dialog when the page scrolls:

Merging the box and the panel
By default the box and the panel are two separate pieces, each with its own border and rounded corners, and the panel casts a shadow over the box:

A popular look is a box and panel which appear as one piece while open: no line between them, and no rounded corners where they meet. The open state is reflected by aria-expanded="true" on the label, so you can select the box on that with :has(). The panel in the body is positioned exactly against the bottom of the box. So the start is making the bottom border of the box transparent and squaring the corners. Give the box and the panel a class of their own:
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="merged" panelStyleClass="merged-panel">
body .ui-selectonemenu.merged:has(> .ui-selectonemenu-label[aria-expanded="true"]) {
border-bottom-color: transparent;
border-bottom-left-radius: 0;
border-bottom-right-radius: 0;
}
The focus ring of the box is a box-shadow, and a ring around the box would draw a line over the top of the panel. So the box gets a ring which stops at its bottom, and the panel a ring which starts at its top. Each shadow is shifted by its own spread, and a clip-path cuts off the doubled ring at the far side. The default theme only exposes the full shorthand --focus-ring, so the color of the ring needs a custom property of its own; rgb(166.2, 213, 250.2) is the one of Saga. The panel gets the focus border color of the box as well.
:root {
--focus-ring-color: rgb(166.2, 213, 250.2);
}
body .ui-selectonemenu.merged.ui-state-focus:not(:has(> .ui-selectonemenu-panel)):has(> .ui-selectonemenu-label[aria-expanded="true"]) {
box-shadow: 0 -.2rem 0 .2rem var(--focus-ring-color);
clip-path: inset(-.2rem calc(-.2rem - 1px) -.2rem round calc(var(--border-radius) + .2rem + 1px) calc(var(--border-radius) + .2rem + 1px) 0 0);
}
body .ui-selectonemenu-panel.merged-panel {
border: 1px solid var(--primary-color);
border-top: 0;
border-top-left-radius: 0;
border-top-right-radius: 0;
box-shadow: 0 .2rem 0 .2rem var(--focus-ring-color);
clip-path: inset(-.2rem calc(-.2rem - 1px) -.2rem round 0 0 calc(var(--border-radius) + .2rem + 1px) calc(var(--border-radius) + .2rem + 1px));
}
The box usually ends at a fractional pixel position. The anti-aliased edges of the box and the panel then meet in the same pixel row, and the blue side borders show a lighter pixel there. You might be tempted to move the panel 1px up so that it overlaps the box. That does nothing: the positioning takes a margin-top and even a translate into account and puts the panel at exactly the same place. A 2px strip below the box paints that pixel row solid instead.
body .ui-selectonemenu.merged.ui-state-focus:not(:has(> .ui-selectonemenu-panel)):has(> .ui-selectonemenu-label[aria-expanded="true"])::after {
content: "";
position: absolute;
left: -1px;
right: -1px;
bottom: -2px;
height: 2px;
border: solid;
border-width: 0 1px;
border-color: inherit;
background: inherit;
}
Now the box and the panel in the body look like one piece:

With appendTo="@this" the panel is a child of the box, so the :not(:has(> .ui-selectonemenu-panel)) above leaves the ring of the box alone: a clip-path on the box would clip the panel as well. The panel already overlaps the bottom border of the box by 1px there, so it covers the ring of the box at the seam by itself. It is however positioned inside the border of the box, so it needs to shift 1px to the left.
body .ui-selectonemenu.merged > .ui-selectonemenu-panel.merged-panel {
margin-left: -1px;
}
Now the panel in @this merges with the box as well:

An invalid box keeps its red border, also while it has focus, and the focus ring stays blue. The panel has to follow. The strip below the box inherits its border color from the box, so that one is red already. The panel reuses the --error-color from "The required and invalid state".
The panel in the body cannot see its box. But only one panel is open at a time, so body:has() can look for the open invalid box.
body:has(.ui-selectonemenu.merged.ui-state-error > .ui-selectonemenu-label[aria-expanded="true"]) > .ui-selectonemenu-panel.merged-panel {
border-color: var(--error-color);
}
Now the panel in the body gets the red border too:

With appendTo="@this" the box is simply the parent of the panel.
body .ui-selectonemenu.merged.ui-state-error > .ui-selectonemenu-panel.merged-panel {
border-color: var(--error-color);
}
And so does the panel in @this:

This look assumes that the panel opens below the box. Scroll the menu to the bottom of the window and open it: there is no room below, so the panel flips above the box, and the merged look breaks:

The flip comes from alignPanel(), which positions the panel with jQuery UI's position() and collision: "flipfit". No attribute turns that off. There are three ways around it. The first is appendTo="@this", because then the panel never flips. The second is subclassing the SelectOneMenu widget and overriding alignPanel(), so that a menu with a never-flip class positions its panel again with collision: "flipfit none": fit horizontally, never flip vertically.
if (PrimeFaces.widget.SelectOneMenu) {
PrimeFaces.widget.SelectOneMenu = class extends PrimeFaces.widget.SelectOneMenu {
alignPanel() {
super.alignPanel();
if (this.jq.hasClass("never-flip") && !this.panel.parent().is(this.jq)) {
this.panel.css({ left: "0px", top: "0px", "transform-origin": "center top" })
.position({ my: "left top", at: "left bottom", of: this.jq, collision: "flipfit none" });
}
}
};
}
PrimeFaces.hideOverlaysOnViewportChange = false;
Load it with <h:outputScript target="head"> inside <h:body>, so that it runs after the PrimeFaces core script and before the widgets are created.
Then give the menu that class:
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="merged never-flip" panelStyleClass="merged-panel">
The panel then opens below the box, past the bottom of the window:

Scrolling the page would close it, so the script also sets PrimeFaces.hideOverlaysOnViewportChange = false, and the panel scrolls along.
The third way is making sure there is room below. A menu at the end of the page gets a padding-bottom below it which is taller than the panel:

This only helps at the end of the page: anywhere else you can still scroll the menu to the bottom of the window.
Also mind the width: this look only works when the panel is exactly as wide as the box, so give the box a fixed width, see "Width of the box and the panel".
The focus which stays
After you click an item, the widget closes the panel and keeps the keyboard focus on the label. This is intentional: a keyboard user can then simply continue with the arrow keys or press Tab to go to the next field. But the label still has focus, so ui-state-focus stays on the root, and the default theme keeps drawing its focus border and shadow until you click somewhere else:

A Tab into the menu gives the same border:

When the menu updates itself via <p:ajax update="@this">, it depends on how the item was selected. After a mouse selection the focus ends up on the body, so there is no focus border:

After a keyboard selection PrimeFaces puts the focus back on the new element, focus border included:

Many workarounds found on the internet instruct to remove the focus with a blur() in an oncomplete. Do not do that: it breaks the keyboard navigation. The browser already knows the difference between focus from the mouse and focus from the keyboard: the :focus-visible pseudo-class. After a mouse selection the label has focus, but it does not match :focus-visible. After a Tab it does. So you can drop the focus look only when the focus did not come from the keyboard.
body .ui-selectonemenu.ui-state-focus:not(:has(:focus-visible)) {
border-color: #ced4da;
box-shadow: none;
}
The #ced4da is the normal input border of the Saga theme, which has unfortunately no variable like --input-border-color or so. Use the one of your own theme. The selector has a higher specificity than the default theme's body .ui-selectonemenu.ui-state-focus, so it needs no !important.
Now a mouse selection leaves no focus border:

And a Tab still gives one:

It works the same with an ajax update of the menu itself. After a mouse selection:

And after a keyboard selection:

The keyboard users keep their focus ring, and the mouse users do not see a menu which looks stuck anymore :)
Tooltips
The itemDescription of an <f:selectItem> or <f:selectItems> ends up as title attribute of the item in the panel, so the browser shows it as tooltip:
<p:selectOneMenu id="country" value="#{bean.country}">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" var="country"
itemLabel="#{country.name}" itemValue="#{country.code}" itemDescription="#{country.capital}" />
</p:selectOneMenu>

With syncTooltip="true" the description of the selected item also becomes the title of the box.
<p:selectOneMenu id="country" value="#{bean.country}" syncTooltip="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" var="country"
itemLabel="#{country.name}" itemValue="#{country.code}" itemDescription="#{country.capital}" />
</p:selectOneMenu>
Hover the box after a selection:

Custom panel content
For more than a tooltip, use var and <p:column>. The var refers to the item value, so the item value must be the whole object, with a converter for it. The panel then renders a table.ui-selectonemenu-table with tr.ui-selectonemenu-row items instead of an ul with li items. The box still shows only the item label. A styleClass on <p:column> ends up on its td. Multiple <p:column> tags give multiple columns, and their headerText gives a header row:
<p:selectOneMenu id="country" value="#{bean.country}" var="country" converter="countryConverter" panelStyleClass="country-panel">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" var="c" itemLabel="#{c.name}" itemValue="#{c}" />
<p:column headerText="Name">#{country.name}</p:column>
<p:column headerText="Code">#{country.code}</p:column>
<p:column headerText="Capital" styleClass="capital">#{country.capital}</p:column>
</p:selectOneMenu>
The capital class makes the capitals gray:
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-table td.capital {
color: var(--text-color-secondary);
}

A single column can also hold more than one line.
<p:selectOneMenu id="country" value="#{bean.country}" var="country" converter="countryConverter" panelStyleClass="country-panel">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" var="c" itemLabel="#{c.name}" itemValue="#{c}" />
<p:column>
<span class="name">#{country.name}</span>
<span class="description">Capital: #{country.capital}</span>
</p:column>
</p:selectOneMenu>
body .ui-selectonemenu-panel.country-panel .ui-selectonemenu-table td .description {
display: block;
font-size: .8em;
color: var(--text-color-secondary);
}
Every item gets a smaller description line below its label:

Fullscreen on small screens
On a phone, a small panel below the box is not very handy. With a media query you can turn the panel into a fullscreen overlay. For the close button, put a button in the footer facet, which is rendered at the bottom of the panel as div.ui-selectonemenu-footer. You'd like to put it in a header facet, but <p:selectOneMenu> doesn't support that: it only has a footer facet. So the CSS below pins it to the top right. The button calls hide() on the widget.
<p:selectOneMenu id="country" widgetVar="country" value="#{bean.country}" panelStyleClass="fullscreen-panel">
<f:selectItems value="#{bean.countries}" />
<f:facet name="footer">
<p:commandButton id="close" type="button" icon="pi pi-times" title="Close"
styleClass="rounded-button ui-button-flat ui-button-secondary" onclick="PF('country').hide()" />
</f:facet>
</p:selectOneMenu>
The CSS hides the footer on large screens. On small screens the panel covers the whole window and scrolls as a whole. The inline top, left and width which the widget script sets need an !important here, and so does the inline max-height of the items wrapper. A sticky band at the top keeps the close button readable while the list scrolls under it, and the filter field sticks right below that band.
body .ui-selectonemenu-panel.fullscreen-panel .ui-selectonemenu-footer {
display: none;
}
@media (max-width: 600px) {
body .ui-selectonemenu-panel.fullscreen-panel {
position: fixed;
inset: 0 !important;
width: auto !important;
border-radius: 0;
overflow-y: auto;
}
body .ui-selectonemenu-panel.fullscreen-panel::before {
content: "";
display: block;
position: sticky;
top: 0;
z-index: 1;
height: 3.5rem;
background: inherit;
}
body .ui-selectonemenu-panel.fullscreen-panel .ui-selectonemenu-items-wrapper {
max-height: none !important;
overflow: visible;
}
body .ui-selectonemenu-panel.fullscreen-panel .ui-selectonemenu-filter-container {
position: sticky;
top: 3.5rem;
z-index: 1;
}
body .ui-selectonemenu-panel.fullscreen-panel .ui-selectonemenu-footer {
display: block;
position: fixed;
top: .5rem;
right: .5rem;
z-index: 2;
}
}
On a phone the panel now covers the whole screen, with the close button at the top right:

With filter="true" the filter field sits right below the close button:

Do not try to turn the panel into a flex container for this. The widget script shows and hides the panel by setting its inline display, and a display: flex !important would keep it open forever.
Native picker on touch screens
On a touch screen, the native picker of the device is often nicer than any panel: a list sheet on Android, a popover menu on iOS. The <p:selectOneMenu> already holds a real <select>. It is only visually hidden. So lay it invisibly over the box on touch screens, and a tap opens the native picker.
@media (pointer: coarse) {
body .ui-selectonemenu.native-on-touch > .ui-helper-hidden-accessible {
inset: 0;
width: auto;
height: auto;
margin: 0;
clip: auto;
z-index: 1;
}
body .ui-selectonemenu.native-on-touch > .ui-helper-hidden-accessible > select {
width: 100%;
height: 100%;
font-size: 16px;
opacity: 0;
}
}
The (pointer: coarse) matches when the primary pointer of the device is a finger. A laptop with a touch screen usually has its trackpad as primary pointer, so it keeps the panel.
The widget does not know that the select was changed natively, so the box would keep its old label. A small subclass lets the box follow the select. It also keeps the focus on the select, because by default the widget moves the focus to the label.
if (PrimeFaces.widget.SelectOneMenu) {
PrimeFaces.widget.SelectOneMenu = class extends PrimeFaces.widget.SelectOneMenu {
init(cfg) {
super.init(cfg);
if (this.jq.hasClass("native-on-touch")) {
this.input.off("focus.ui-selectonemenu")
.on("focus.native-on-touch", () => this.toggleFocus(true))
.on("blur.native-on-touch", () => this.toggleFocus(false))
.on("change.native-on-touch", () => {
const option = this.input.find("option:selected");
this.setLabel(option.text() || "\xa0");
this.value = option.val();
});
}
}
toggleFocus(focused) {
this.jq.toggleClass("ui-state-focus", focused);
this.menuIcon.toggleClass("ui-state-focus", focused);
}
};
}
Load it with <h:outputScript target="head"> inside <h:body>, so that it runs after the PrimeFaces core script and before the widgets are created.
Then give the menu that class:
<p:selectOneMenu id="country" value="#{bean.country}" styleClass="native-on-touch">
A <p:ajax> or your own onchange needs nothing extra: PrimeFaces renders both as the onchange of that same select, and a regular submit sends its value as usual. A tap now opens the native picker, here on Android and on iOS:

With a mouse nothing changes: the panel opens as usual. This is verified on Chrome for Android and on Safari for iOS.
The placeholder item
A "please select" placeholder is simply an <f:selectItem> with itemValue="#{null}". It must be #{null}; an empty itemValue="" is not the same. The label is up to you, an empty itemLabel="" is fine too. With required="true", an untouched submit then fails with "Value is required".
<p:selectOneMenu id="country" value="#{bean.country}" required="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
Note that there is no noSelectionOption="true". Despite its name, that attribute does not make a placeholder. It only does something together with hideNoSelectionOption on the menu. On a standard <h:selectOneMenu> the pair hides the item once a value is selected and the menu is rendered again. While the value is null the placeholder is in the list:
<h:selectOneMenu id="country" value="#{bean.country}" required="true" hideNoSelectionOption="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" noSelectionOption="true" />
<f:selectItems value="#{bean.countries}" />
</h:selectOneMenu>

Select a country and submit the form. The menu is rendered again with the selected value:

Now the placeholder is gone from the list, so that the enduser cannot go back to it:

PrimeFaces does it differently. A <p:selectOneMenu hideNoSelectionOption="true"> drops the item altogether, also while the value is null. You could as good omit the whole <f:selectItem> altogether.
<p:selectOneMenu id="country" value="#{bean.country}" required="true" hideNoSelectionOption="true">
<f:selectItem itemValue="#{null}" itemLabel="Select a country" noSelectionOption="true" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
The placeholder is never rendered. The hidden <select> falls back to its first option, and the box shows that item as if the enduser selected it:

The panel has no placeholder either:

Submitting the form untouched sends the value of that item. The required="true" does not notice anything, and the model silently gets the first country. Make the attribute depend on the value instead, and update the menu on change. This is also what the PrimeFaces showcase does.
<p:selectOneMenu id="country" value="#{bean.country}" required="true" hideNoSelectionOption="#{not empty bean.country}">
<p:ajax update="@this" />
<f:selectItem itemValue="#{null}" itemLabel="Select a country" noSelectionOption="true" />
<f:selectItems value="#{bean.countries}" />
</p:selectOneMenu>
Now the placeholder shows while the value is null:

And it is in the panel:

So use the two attributes as a pair or not at all. A lone noSelectionOption="true" does nothing useful, and sooner or later someone completes it with a literal hideNoSelectionOption="true". A lone hideNoSelectionOption does nothing either.
In practice the simplest is to not use noSelectionOption at all. It does not do what most people think it does. A plain placeholder with itemValue="#{null}", together with required="true", is all you need. Many articles and examples on the internet get this wrong. If your AI model still generates PrimeFaces pages with a lone noSelectionOption="true" or a literal hideNoSelectionOption="true", then install claude-faces-expert. It makes your coding agent aware of exactly this pitfall, and of many more Jakarta Faces pitfalls.
Why this article
Google stopped passing search keywords to websites years ago. They only show up in Google Search Console, and that one is not exactly easy to dig through. So I let Claude dig through the Search Console of this blog, to find out which search keywords brought people here. Quite some of them ended up in articles which did not answer their question at all. Over the last three months it found a bunch of searches like these:
| Query | Impressions |
|---|---|
| primefaces selectonemenu ui-state-focus class | 160 |
| primefaces ui-state-focus class selectonemenu | 91 |
| primefaces selectonemenu appendto attribute | 80 |
| ui-selectonemenu-panel primefaces css class | 77 |
| primefaces selectonemenu panel css class ui-selectonemenu-panel | 70 |
| ui-selectonemenu-focus class primefaces | 31 |
| ui-selectonemenu-open class primefaces | 22 |
| primefaces p-focus css class | 18 |
| primefaces selectonemenu ui-state-focus remains after ajax update | 16 |
Together roughly 1,100 impressions, and not a single click. Google showed these searchers three of my old articles: "Set focus and highlight in JSF", "Objects in h:selectOneMenu" and "Styling options in h:selectOneMenu". Those are from 2007 and 2008, about the plain JSF 1.x <h:selectOneMenu>. Google matched them on "focus", "selectOneMenu" and "styling", but they say nothing about the classes, the panel and the appendTo of PrimeFaces <p:selectOneMenu>. So the searchers rightly moved on.
Some of the searched classes do not even exist in PrimeFaces, see "The state classes". This article is the answer to all of them :)

No comments:
Post a Comment