Sunday, November 22, 2026

PrimeFaces p:selectOneMenu styling guide

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>

A closed p:selectOneMenu

And an overlay panel with the options:

An open p:selectOneMenu

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">&nbsp;</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:

A pill shaped p:selectOneMenu with a light gray background

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.

ClassSet onWhen
ui-state-hoverroot and triggermouse is over the box, but only while it does not have focus
ui-state-focusroot and triggerthe label has keyboard focus
ui-state-errorroot and triggerthe component is invalid after validation
ui-state-disabledroot, or individual itemsdisabled="true" on the menu or on a <f:selectItem>
ui-state-readonlyrootreadonly="true"
ui-state-hoveritemmouse is over the item
ui-state-highlightitemthe item is the currently selected one
ui-inputwrapper-focusrootthe label has focus, only inside .ui-float-label
ui-inputwrapper-filledrootthe 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:

A focused p:selectOneMenu with a white gap and 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 p:selectOneMenu with a thicker blue left border

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>

An invalid p:selectOneMenu with its message and submit button

It keeps its red border while it is open:

The open panel of an invalid p:selectOneMenu

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:

An invalid p:selectOneMenu with a light red background and a red trigger icon

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>

A disabled 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:

A disabled p:selectOneMenu with a gray background

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 open panel of the readonly 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:

A readonly p:selectOneMenu with a slight opacity

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:

A p:selectOneMenu in a floating label, with the label in the box

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

The open p:selectOneMenu in a floating label, with the label floated 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:

The floating label stays above the box with a selected value

Also while the panel is open:

The open panel with the selected value highlighted

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 floating label in the primary color while the menu has focus

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:

The open panel with "No country" as first item

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:

The open panel with unstyled items

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:

The panel with square right corners, circled in red

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:

The panel with round right corners

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:

The open panel with italic but not red items

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:

The open panel with italic red items

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:

The panel with max-height in CSS, still 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 panel with the height attribute, 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>

An open p:selectOneMenu with grouped items

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:

The open panel with small uppercase group headers on a light background

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>

The open panel with the filter field above the items

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:

The open panel with the search icon on the right side of the filter field

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:

The open panel with all countries

With the checkbox only the European ones are left:

The open panel with only the European countries

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:

The open panel, a bit 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>

A p:selectOneMenu taking the full width of its .ui-fluid parent

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:

A p:selectOneMenu with a width in CSS, still as wide as its longest option

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:

A 12em wide p:selectOneMenu with a hard cut label and a wider panel

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:

A 12em wide p:selectOneMenu with an ellipsis on the label

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 capped panel with an ellipsis on the items

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 capped panel with wrapped items

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:

The open panel in @this, exactly as wide as the box

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:

The panel in body escapes the dashed box

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:

The panel in @this is clipped by the dashed box

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:

The open panel in body over a scrolling dashed box

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

The open panel in @this inside the scrolling dashed box

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:

The open panel inside a p:dialog

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:

The open panel as separate piece below 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:

The open panel in body merged with the box

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:

The open panel in @this merged with the box

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:

The open panel in body with a red border

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:

The open panel in @this with a red border

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 panel flipped above the box, with the merged look broken

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:

The panel 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:

The panel opens below the box

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:

The focus border stays after a mouse selection

A Tab into the menu gives the same border:

The focus border after a Tab

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:

No focus border after a mouse selection with an ajax update

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

The focus border after a keyboard selection with an ajax update

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:

No focus border after a mouse selection with :focus-visible

And a Tab still gives one:

The focus border after a Tab with :focus-visible

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

No focus border after a mouse selection with an ajax update and :focus-visible

And after a keyboard selection:

The focus border after a keyboard selection with an ajax update and :focus-visible

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>

The open panel with the capital as tooltip on the hovered item

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:

The closed box with the capital of the selected country as tooltip

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);
}

The open panel with Name, Code and Capital columns

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:

The open panel with a description line below each 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:

The fullscreen panel with the close button at the top right

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

The fullscreen panel with the filter field 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:

The native picker on Android The native picker 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>

An open h:selectOneMenu with the placeholder at the top of the list

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

The h:selectOneMenu with Belgium selected after the submit

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

The reopened h:selectOneMenu without the placeholder in the list

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:

A p:selectOneMenu showing the first country while the value is null

The panel has no placeholder either:

The open panel without placeholder

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:

A p:selectOneMenu showing its placeholder while the value is null

And it is in the panel:

The open panel with the placeholder

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:

QueryImpressions
primefaces selectonemenu ui-state-focus class160
primefaces ui-state-focus class selectonemenu91
primefaces selectonemenu appendto attribute80
ui-selectonemenu-panel primefaces css class77
primefaces selectonemenu panel css class ui-selectonemenu-panel70
ui-selectonemenu-focus class primefaces31
ui-selectonemenu-open class primefaces22
primefaces p-focus css class18
primefaces selectonemenu ui-state-focus remains after ajax update16

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: