From 124849ca19f554ed18c0fc38d3f86c9926f68e3e Mon Sep 17 00:00:00 2001
From: "Snyder, Chris" <SnyC1Vv@sutterhealth.org>
Date: Thu, 30 Jul 2026 13:18:48 -0400
Subject: [PATCH 1/4] fix: give facet options search input an accessible name
 by default (#692)

The options search input rendered by FilterGroup only received an
associated label when showOptionsSearchInputLabel was enabled, so by
default its accessible name fell back to the shared "Search here..."
placeholder.

The label text is now always generated and associated with the input;
showOptionsSearchInputLabel only controls whether it is visible, via a
new visuallyHiddenLabel prop on Filters.SearchInput. FacetsProps also
accepts showOptionsSearchInputLabel so auto-rendered facets can show
the label without declaring a child override per facet.
---
 docs/search-ui-react.facetsprops.md           | 19 +++++++++++
 ...facetsprops.showoptionssearchinputlabel.md | 18 +++++++++++
 docs/search-ui-react.filtergroupprops.md      |  2 +-
 ...rgroupprops.showoptionssearchinputlabel.md |  7 +++-
 docs/search-ui-react.standardfacetprops.md    |  2 +-
 ...dfacetprops.showoptionssearchinputlabel.md |  7 +++-
 docs/search-ui-react.staticfiltersprops.md    |  2 +-
 ...iltersprops.showoptionssearchinputlabel.md |  7 +++-
 etc/search-ui-react.api.md                    |  3 +-
 src/components/FacetProps.ts                  | 14 +++++---
 src/components/Facets.tsx                     |  8 ++++-
 src/components/FilterGroup.tsx                | 18 +++++++----
 src/components/Filters/SearchInput.tsx        | 21 +++++++++---
 tests/components/Facets.test.tsx              | 32 ++++++++++++++++++-
 .../components/NumericalFacetContent.test.tsx | 14 +++++++-
 .../components/StandardFacetContent.test.tsx  | 14 +++++++-
 tests/components/StaticFilters.test.tsx       | 11 ++++++-
 17 files changed, 173 insertions(+), 26 deletions(-)
 create mode 100644 docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md

diff --git a/docs/search-ui-react.facetsprops.md b/docs/search-ui-react.facetsprops.md
index b9e421871..e1b681b0a 100644
--- a/docs/search-ui-react.facetsprops.md
+++ b/docs/search-ui-react.facetsprops.md
@@ -148,6 +148,25 @@ boolean
 _(Optional)_ Whether or not a search is automatically run when a filter is selected. Defaults to true.
 
 
+</td></tr>
+<tr><td>
+
+[showOptionsSearchInputLabel?](./search-ui-react.facetsprops.showoptionssearchinputlabel.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Whether or not to display the options search input label visibly on every rendered facet. Defaults to false, and is overridden by the same prop on a child facet.
+
+
 </td></tr>
 </tbody></table>
 
diff --git a/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md b/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md
new file mode 100644
index 000000000..587d04467
--- /dev/null
+++ b/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/search-ui-react](./search-ui-react.md) &gt; [FacetsProps](./search-ui-react.facetsprops.md) &gt; [showOptionsSearchInputLabel](./search-ui-react.facetsprops.showoptionssearchinputlabel.md)
+
+## FacetsProps.showOptionsSearchInputLabel property
+
+Whether or not to display the options search input label visibly on every rendered facet. Defaults to false, and is overridden by the same prop on a child facet.
+
+**Signature:**
+
+```typescript
+showOptionsSearchInputLabel?: boolean;
+```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+
diff --git a/docs/search-ui-react.filtergroupprops.md b/docs/search-ui-react.filtergroupprops.md
index ef91c8db0..741cb9942 100644
--- a/docs/search-ui-react.filtergroupprops.md
+++ b/docs/search-ui-react.filtergroupprops.md
@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to display the visible search input label. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>
diff --git a/docs/search-ui-react.filtergroupprops.showoptionssearchinputlabel.md b/docs/search-ui-react.filtergroupprops.showoptionssearchinputlabel.md
index f9fcf5dd3..a8512ceeb 100644
--- a/docs/search-ui-react.filtergroupprops.showoptionssearchinputlabel.md
+++ b/docs/search-ui-react.filtergroupprops.showoptionssearchinputlabel.md
@@ -4,10 +4,15 @@
 
 ## FilterGroupProps.showOptionsSearchInputLabel property
 
-Whether or not to display the visible search input label. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+
diff --git a/docs/search-ui-react.standardfacetprops.md b/docs/search-ui-react.standardfacetprops.md
index 01eeb0d4e..e481e192a 100644
--- a/docs/search-ui-react.standardfacetprops.md
+++ b/docs/search-ui-react.standardfacetprops.md
@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to show the label for the search bar when present. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>
diff --git a/docs/search-ui-react.standardfacetprops.showoptionssearchinputlabel.md b/docs/search-ui-react.standardfacetprops.showoptionssearchinputlabel.md
index ec43d2479..a8449e15d 100644
--- a/docs/search-ui-react.standardfacetprops.showoptionssearchinputlabel.md
+++ b/docs/search-ui-react.standardfacetprops.showoptionssearchinputlabel.md
@@ -4,10 +4,15 @@
 
 ## StandardFacetProps.showOptionsSearchInputLabel property
 
-Whether or not to show the label for the search bar when present. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+
diff --git a/docs/search-ui-react.staticfiltersprops.md b/docs/search-ui-react.staticfiltersprops.md
index 4ad9fdbce..595e2ec16 100644
--- a/docs/search-ui-react.staticfiltersprops.md
+++ b/docs/search-ui-react.staticfiltersprops.md
@@ -183,7 +183,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to display the visible search input label. Defaults to false.
+_(Optional)_ Whether or not to display the search input label visibly. Defaults to false.
 
 
 </td></tr>
diff --git a/docs/search-ui-react.staticfiltersprops.showoptionssearchinputlabel.md b/docs/search-ui-react.staticfiltersprops.showoptionssearchinputlabel.md
index af6b96e41..fb6ba1909 100644
--- a/docs/search-ui-react.staticfiltersprops.showoptionssearchinputlabel.md
+++ b/docs/search-ui-react.staticfiltersprops.showoptionssearchinputlabel.md
@@ -4,10 +4,15 @@
 
 ## StaticFiltersProps.showOptionsSearchInputLabel property
 
-Whether or not to display the visible search input label. Defaults to false.
+Whether or not to display the search input label visibly. Defaults to false.
 
 **Signature:**
 
 ```typescript
 showOptionsSearchInputLabel?: boolean;
 ```
+
+## Remarks
+
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+
diff --git a/etc/search-ui-react.api.md b/etc/search-ui-react.api.md
index 9e8114b2e..a48a61f8b 100644
--- a/etc/search-ui-react.api.md
+++ b/etc/search-ui-react.api.md
@@ -262,6 +262,7 @@ export interface FacetsProps {
     hierarchicalFieldIds?: string[];
     onlyRenderChildren?: boolean;
     searchOnChange?: boolean;
+    showOptionsSearchInputLabel?: boolean;
 }
 
 // @public
@@ -1174,7 +1175,7 @@ export interface VisualAutocompleteConfig {
 
 // Warnings were encountered during analysis:
 //
-// dist/index.d.ts:1921:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
+// dist/index.d.ts:1933:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/src/components/FacetProps.ts b/src/components/FacetProps.ts
index 282aaa5f3..12c8f071e 100644
--- a/src/components/FacetProps.ts
+++ b/src/components/FacetProps.ts
@@ -33,6 +33,15 @@ export interface FacetsProps {
   excludedFieldIds?: string[],
   /** List of field ids that should be rendered as hierarchical facets. */
   hierarchicalFieldIds?: string[],
+  /**
+   * Whether or not to display the options search input label visibly on every rendered facet.
+   * Defaults to false, and is overridden by the same prop on a child facet.
+   *
+   * @remarks
+   * The label is always associated with the search input so that it has an accessible name.
+   * When false, the label is visually hidden but remains available to assistive technology.
+   */
+  showOptionsSearchInputLabel?: boolean,
   /** The custom facet components that will override the default rendering.
    *
    * @remarks
@@ -66,10 +75,7 @@ export interface StandardFacetProps {
   showMoreLimit?: number,
   /** CSS classes for customizing the component styling. */
   customCssClasses?: FilterGroupCssClasses,
-  /**
-   * Whether or not to show the label for the search bar when present.
-   * Defaults to false.
-   */
+  /** {@inheritDoc FilterGroupProps.showOptionsSearchInputLabel} */
   showOptionsSearchInputLabel?: boolean
 }
 
diff --git a/src/components/Facets.tsx b/src/components/Facets.tsx
index 871abad0f..1c5d51038 100644
--- a/src/components/Facets.tsx
+++ b/src/components/Facets.tsx
@@ -40,6 +40,7 @@ export function Facets(props: FacetsProps): React.JSX.Element {
     hierarchicalFieldIds,
     excludedFieldIds = [],
     customCssClasses = {},
+    showOptionsSearchInputLabel,
   } = props;
   const resolvedHierarchicalFieldIds = useMemo(() => hierarchicalFieldIds ?? [], [hierarchicalFieldIds]);
 
@@ -89,6 +90,7 @@ export function Facets(props: FacetsProps): React.JSX.Element {
                     facetsCustomCssClasses={customCssClasses}
                     fieldIdToCustomFacetProps={fieldIdToCustomFacetProps}
                     hierarchicalFieldIds={resolvedHierarchicalFieldIds}
+                    showOptionsSearchInputLabel={showOptionsSearchInputLabel}
                   />
                   {(i < facets.length - 1)
                     && <FilterDivider className={customCssClasses?.divider}/>}
@@ -140,6 +142,7 @@ export function HierarchicalFacet(props: HierarchicalFacetProps) { return null;
  * @param facetsCustomCssClasses - {@link FacetsCssClasses}
  * @param fieldIdToCustomFacetProps - a map of fieldId to facet props
  * @param hierarchicalFieldIds - a list of hierarchical field ids
+ * @param showOptionsSearchInputLabel - whether to display the options search input label visibly
  * @returns {@link ReactElement}
  *
  * @internal
@@ -149,16 +152,19 @@ export function Facet({
   facetsCustomCssClasses,
   fieldIdToCustomFacetProps,
   hierarchicalFieldIds,
+  showOptionsSearchInputLabel,
 }: {
   facet: DisplayableFacet,
   facetsCustomCssClasses: FacetsCssClasses,
   fieldIdToCustomFacetProps: Map<string, any>,
-  hierarchicalFieldIds: string[]
+  hierarchicalFieldIds: string[],
+  showOptionsSearchInputLabel?: boolean
 }) {
   let facetType: FacetType;
   let facetProps: FacetProps = {
     fieldId: facet.fieldId,
     label: facet.displayName,
+    ...showOptionsSearchInputLabel !== undefined && { showOptionsSearchInputLabel },
   };
   const customFacetElement = fieldIdToCustomFacetProps.get(facet.fieldId);
   if (customFacetElement) {
diff --git a/src/components/FilterGroup.tsx b/src/components/FilterGroup.tsx
index a90a9b7de..ad77bd3bb 100644
--- a/src/components/FilterGroup.tsx
+++ b/src/components/FilterGroup.tsx
@@ -50,7 +50,13 @@ export interface FilterGroupProps {
   defaultExpanded?: boolean,
   /** Whether or not to display a text input to search for filter options. */
   searchable?: boolean,
-  /** Whether or not to display the visible search input label. Defaults to false. */
+  /**
+   * Whether or not to display the search input label visibly. Defaults to false.
+   *
+   * @remarks
+   * The label is always associated with the search input so that it has an accessible name.
+   * When false, the label is visually hidden but remains available to assistive technology.
+   */
   showOptionsSearchInputLabel?: boolean,
   /** CSS classes for customizing the component styling. */
   customCssClasses?: FilterGroupCssClasses,
@@ -83,11 +89,9 @@ export function FilterGroup({
       ...optionInput && { input: optionInput }
     };
   }, [customCssClasses]);
-  const searchInputLabel = showOptionsSearchInputLabel
-    ? t('filterGroupSearchInputLabel', {
-      title
-    })
-    : undefined;
+  const searchInputLabel = t('filterGroupSearchInputLabel', {
+    title
+  });
 
   return (
     <FilterGroupProvider
@@ -106,6 +110,7 @@ export function FilterGroup({
               className={cssClasses.searchInput}
               labelClassName={cssClasses.searchInputLabel}
               label={searchInputLabel}
+              visuallyHiddenLabel={!showOptionsSearchInputLabel}
             />}
           <CheckboxOptions
             filterOptions={filterOptions}
@@ -120,6 +125,7 @@ export function FilterGroup({
               className={cssClasses.searchInput}
               labelClassName={cssClasses.searchInputLabel}
               label={searchInputLabel}
+              visuallyHiddenLabel={!showOptionsSearchInputLabel}
             />}
           <CheckboxOptions
             filterOptions={filterOptions}
diff --git a/src/components/Filters/SearchInput.tsx b/src/components/Filters/SearchInput.tsx
index daeea0122..b7e218edb 100644
--- a/src/components/Filters/SearchInput.tsx
+++ b/src/components/Filters/SearchInput.tsx
@@ -15,8 +15,16 @@ export interface SearchInputProps {
   labelClassName?: string,
   /** {@inheritDoc FilterSearch.placeholder} */
   placeholder?: string,
-  /** The visible label text associated with the input. */
-  label?: string
+  /** The label text associated with the input. */
+  label?: string,
+  /**
+   * Whether the label is hidden from view while remaining associated with the input for
+   * assistive technology. Defaults to false.
+   *
+   * @remarks
+   * When true, labelClassName is not applied since the label is not rendered visibly.
+   */
+  visuallyHiddenLabel?: boolean
 }
 
 /**
@@ -33,7 +41,8 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
     className = 'text-sm form-input bg-white h-9 w-full outline-none p-2 mb-2 rounded-md border border-gray-300 focus:ring-primary focus:ring-0 text-neutral-dark placeholder:text-neutral',
     labelClassName = 'mb-1 block text-sm font-medium text-neutral-dark',
     placeholder,
-    label
+    label,
+    visuallyHiddenLabel = false
   } = props;
   const { searchValue, setSearchValue } = useFilterGroupContext();
   const handleChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
@@ -45,7 +54,11 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
   return (
     <>
       {label && (
-        <label id={labelId} htmlFor={inputId} className={labelClassName}>
+        <label
+          id={labelId}
+          htmlFor={inputId}
+          className={visuallyHiddenLabel ? 'sr-only' : labelClassName}
+        >
           {label}
         </label>
       )}
diff --git a/tests/components/Facets.test.tsx b/tests/components/Facets.test.tsx
index 6b91a0d6d..86c499886 100644
--- a/tests/components/Facets.test.tsx
+++ b/tests/components/Facets.test.tsx
@@ -133,7 +133,37 @@ describe('Facets', () => {
         />
       </Facets>);
 
-    expect(screen.getByText('Search Products Options')).toBeDefined();
+    expect(screen.getByText('Search Products Options')).not.toHaveClass('sr-only');
+    expect(screen.getByLabelText('Search Products Options')).toBeDefined();
+  });
+
+  it('Associates a visually hidden options search input label by default', () => {
+    render(
+      <Facets onlyRenderChildren={true}>
+        <StandardFacet fieldId='products' showMoreLimit={1}/>
+      </Facets>);
+
+    expect(screen.getByText('Search Products Options')).toHaveClass('sr-only');
+    expect(screen.getByLabelText('Search Products Options')).toBeDefined();
+  });
+
+  it('Passes the options search input label setting from Facets to a facet', () => {
+    render(
+      <Facets onlyRenderChildren={true} showOptionsSearchInputLabel={true}>
+        <StandardFacet fieldId='products' showMoreLimit={1}/>
+      </Facets>);
+
+    expect(screen.getByText('Search Products Options')).not.toHaveClass('sr-only');
+    expect(screen.getByLabelText('Search Products Options')).toBeDefined();
+  });
+
+  it('A facet overrides the options search input label setting from Facets', () => {
+    render(
+      <Facets onlyRenderChildren={true} showOptionsSearchInputLabel={true}>
+        <StandardFacet fieldId='products' showMoreLimit={1} showOptionsSearchInputLabel={false}/>
+      </Facets>);
+
+    expect(screen.getByText('Search Products Options')).toHaveClass('sr-only');
     expect(screen.getByLabelText('Search Products Options')).toBeDefined();
   });
 
diff --git a/tests/components/NumericalFacetContent.test.tsx b/tests/components/NumericalFacetContent.test.tsx
index 42e026e1d..5424cc2e1 100644
--- a/tests/components/NumericalFacetContent.test.tsx
+++ b/tests/components/NumericalFacetContent.test.tsx
@@ -169,7 +169,19 @@ describe('NumericalFacetContent', () => {
       showOptionsSearchInputLabel: true
     }));
 
-    expect(screen.getByText(`Search ${numericalFacet.displayName} Options`)).toBeDefined();
+    const label = screen.getByText(`Search ${numericalFacet.displayName} Options`);
+    expect(label).not.toHaveClass('sr-only');
+    expect(screen.getByLabelText(`Search ${numericalFacet.displayName} Options`)).toBeDefined();
+  });
+
+  it('Associates a visually hidden options search input label by default', () => {
+    render(mockNumericalFacet({
+      fieldId: numericalFacet.fieldId,
+      showMoreLimit: 1
+    }));
+
+    const label = screen.getByText(`Search ${numericalFacet.displayName} Options`);
+    expect(label).toHaveClass('sr-only');
     expect(screen.getByLabelText(`Search ${numericalFacet.displayName} Options`)).toBeDefined();
   });
 });
diff --git a/tests/components/StandardFacetContent.test.tsx b/tests/components/StandardFacetContent.test.tsx
index e14a74a3e..0188078da 100644
--- a/tests/components/StandardFacetContent.test.tsx
+++ b/tests/components/StandardFacetContent.test.tsx
@@ -113,7 +113,19 @@ describe('StandardFacetContent', () => {
       showOptionsSearchInputLabel: true
     }));
 
-    expect(screen.getByText(`Search ${standardFacet.displayName} Options`)).toBeDefined();
+    const label = screen.getByText(`Search ${standardFacet.displayName} Options`);
+    expect(label).not.toHaveClass('sr-only');
+    expect(screen.getByLabelText(`Search ${standardFacet.displayName} Options`)).toBeDefined();
+  });
+
+  it('Associates a visually hidden options search input label by default', () => {
+    render(mockStandardFacet({
+      fieldId: standardFacet.fieldId,
+      showMoreLimit: 1
+    }));
+
+    const label = screen.getByText(`Search ${standardFacet.displayName} Options`);
+    expect(label).toHaveClass('sr-only');
     expect(screen.getByLabelText(`Search ${standardFacet.displayName} Options`)).toBeDefined();
   });
 });
diff --git a/tests/components/StaticFilters.test.tsx b/tests/components/StaticFilters.test.tsx
index d7a487d2c..18e62178d 100644
--- a/tests/components/StaticFilters.test.tsx
+++ b/tests/components/StaticFilters.test.tsx
@@ -182,7 +182,16 @@ describe('Static Filters', () => {
       />
     );
 
-    expect(screen.getByText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
+    const label = screen.getByText(`Search ${staticFiltersProps.title} Options`);
+    expect(label).not.toHaveClass('sr-only');
+    expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
+  });
+
+  it('Associates a visually hidden search input label by default', () => {
+    render(<StaticFilters {...staticFiltersProps} searchable={true} />);
+
+    const label = screen.getByText(`Search ${staticFiltersProps.title} Options`);
+    expect(label).toHaveClass('sr-only');
     expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
   });
 

From bb77301994f4945ea9d45888b7f3b2ab6cc9978c Mon Sep 17 00:00:00 2001
From: "Snyder, Chris" <SnyC1Vv@sutterhealth.org>
Date: Thu, 30 Jul 2026 13:37:24 -0400
Subject: [PATCH 2/4] fix: keep search input first in its container when its
 label is hidden

Rendering the visually hidden label ahead of the input made the input a
non-first child of the surrounding space-y-3 container, which gave it a
0.75rem top margin that it did not have when no label was rendered. The
hidden label now follows the input instead, leaving the default layout
unchanged.
---
 docs/search-ui-react.facetsprops.md           |  2 +-
 ...facetsprops.showoptionssearchinputlabel.md |  4 ++--
 etc/search-ui-react.api.md                    |  2 +-
 src/components/FacetProps.ts                  |  5 ++--
 src/components/Filters/SearchInput.tsx        | 24 ++++++++++++-------
 tests/components/StaticFilters.test.tsx       | 14 +++++++++++
 6 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/docs/search-ui-react.facetsprops.md b/docs/search-ui-react.facetsprops.md
index e1b681b0a..516e136d4 100644
--- a/docs/search-ui-react.facetsprops.md
+++ b/docs/search-ui-react.facetsprops.md
@@ -164,7 +164,7 @@ boolean
 
 </td><td>
 
-_(Optional)_ Whether or not to display the options search input label visibly on every rendered facet. Defaults to false, and is overridden by the same prop on a child facet.
+_(Optional)_ Whether or not to display the options search input label visibly on facets that render an options search input. Defaults to false, and is overridden by the same prop on a child facet.
 
 
 </td></tr>
diff --git a/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md b/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md
index 587d04467..4665cf662 100644
--- a/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md
+++ b/docs/search-ui-react.facetsprops.showoptionssearchinputlabel.md
@@ -4,7 +4,7 @@
 
 ## FacetsProps.showOptionsSearchInputLabel property
 
-Whether or not to display the options search input label visibly on every rendered facet. Defaults to false, and is overridden by the same prop on a child facet.
+Whether or not to display the options search input label visibly on facets that render an options search input. Defaults to false, and is overridden by the same prop on a child facet.
 
 **Signature:**
 
@@ -14,5 +14,5 @@ showOptionsSearchInputLabel?: boolean;
 
 ## Remarks
 
-The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology.
+The label is always associated with the search input so that it has an accessible name. When false, the label is visually hidden but remains available to assistive technology. Hierarchical facets do not render an options search input, so this has no effect on them.
 
diff --git a/etc/search-ui-react.api.md b/etc/search-ui-react.api.md
index a48a61f8b..564351e4b 100644
--- a/etc/search-ui-react.api.md
+++ b/etc/search-ui-react.api.md
@@ -1175,7 +1175,7 @@ export interface VisualAutocompleteConfig {
 
 // Warnings were encountered during analysis:
 //
-// dist/index.d.ts:1933:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
+// dist/index.d.ts:1934:5 - (ae-forgotten-export) The symbol "translations" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/src/components/FacetProps.ts b/src/components/FacetProps.ts
index 12c8f071e..9236966bc 100644
--- a/src/components/FacetProps.ts
+++ b/src/components/FacetProps.ts
@@ -34,12 +34,13 @@ export interface FacetsProps {
   /** List of field ids that should be rendered as hierarchical facets. */
   hierarchicalFieldIds?: string[],
   /**
-   * Whether or not to display the options search input label visibly on every rendered facet.
-   * Defaults to false, and is overridden by the same prop on a child facet.
+   * Whether or not to display the options search input label visibly on facets that render an
+   * options search input. Defaults to false, and is overridden by the same prop on a child facet.
    *
    * @remarks
    * The label is always associated with the search input so that it has an accessible name.
    * When false, the label is visually hidden but remains available to assistive technology.
+   * Hierarchical facets do not render an options search input, so this has no effect on them.
    */
   showOptionsSearchInputLabel?: boolean,
   /** The custom facet components that will override the default rendering.
diff --git a/src/components/Filters/SearchInput.tsx b/src/components/Filters/SearchInput.tsx
index b7e218edb..51334f8ad 100644
--- a/src/components/Filters/SearchInput.tsx
+++ b/src/components/Filters/SearchInput.tsx
@@ -51,17 +51,18 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
 
   const labelId = useId('filters-search-input-label');
   const inputId = useId('filter-group-search-input');
+  const labelElement = label && (
+    <label
+      id={labelId}
+      htmlFor={inputId}
+      className={visuallyHiddenLabel ? 'sr-only' : labelClassName}
+    >
+      {label}
+    </label>
+  );
   return (
     <>
-      {label && (
-        <label
-          id={labelId}
-          htmlFor={inputId}
-          className={visuallyHiddenLabel ? 'sr-only' : labelClassName}
-        >
-          {label}
-        </label>
-      )}
+      {!visuallyHiddenLabel && labelElement}
       <input
         id={inputId}
         className={className}
@@ -70,6 +71,11 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
         value={searchValue}
         onChange={handleChange}
       />
+      {/* A hidden label follows the input so that the input remains the first child of its
+          container. Sibling spacing utilities such as Tailwind's space-y-* skip the first child,
+          so a preceding label would add a gap above the input even though the label itself takes
+          up no space. htmlFor keeps the association regardless of order. */}
+      {visuallyHiddenLabel && labelElement}
     </>
   );
 }
diff --git a/tests/components/StaticFilters.test.tsx b/tests/components/StaticFilters.test.tsx
index 18e62178d..a091277eb 100644
--- a/tests/components/StaticFilters.test.tsx
+++ b/tests/components/StaticFilters.test.tsx
@@ -195,6 +195,20 @@ describe('Static Filters', () => {
     expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
   });
 
+  it('Keeps the search input first in its container when the label is visually hidden', () => {
+    render(<StaticFilters {...staticFiltersProps} searchable={true} />);
+
+    const searchInput = screen.getByRole('textbox');
+    const label = screen.getByText(`Search ${staticFiltersProps.title} Options`);
+
+    // Sibling order is the subject here: an element in front of the input gives it a space-y-*
+    // margin that the input should not have when the label is hidden.
+    /* eslint-disable testing-library/no-node-access */
+    expect(searchInput.previousElementSibling).toBeNull();
+    expect(searchInput.nextElementSibling).toBe(label);
+    /* eslint-enable testing-library/no-node-access */
+  });
+
   it('Clicking a filter option executes a search when searchOnChange is true', async () => {
     const actions = spyOnActions();
     render(<StaticFilters {...staticFiltersProps} />);

From 967bebb22e71797a3a915cf4626824be8d6a2585 Mon Sep 17 00:00:00 2001
From: "Snyder, Chris" <SnyC1Vv@sutterhealth.org>
Date: Thu, 30 Jul 2026 14:18:41 -0400
Subject: [PATCH 3/4] fix: allow filterGroupSearchInputLabel as a translation
 override key

The key exists in every locale file but was missing from the
translationKeys union, so overriding the facet options search input
label through SearchI18nextProvider was a type error.
---
 src/components/SearchI18nextProvider.tsx      |  1 +
 .../components/SearchI18nextProvider.test.tsx | 46 +++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 tests/components/SearchI18nextProvider.test.tsx

diff --git a/src/components/SearchI18nextProvider.tsx b/src/components/SearchI18nextProvider.tsx
index 707efcae2..a053c8788 100644
--- a/src/components/SearchI18nextProvider.tsx
+++ b/src/components/SearchI18nextProvider.tsx
@@ -28,6 +28,7 @@ type translationKeys =
   'dismiss' |
   'dropDownScreenReaderInstructions' |
   'feedback' |
+  'filterGroupSearchInputLabel' |
   'invalidRange' |
   'max' |
   'min' |
diff --git a/tests/components/SearchI18nextProvider.test.tsx b/tests/components/SearchI18nextProvider.test.tsx
new file mode 100644
index 000000000..8518edfbd
--- /dev/null
+++ b/tests/components/SearchI18nextProvider.test.tsx
@@ -0,0 +1,46 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { SearchHeadlessContext } from '@yext/search-headless-react';
+import {
+  SearchI18nextProvider,
+  SearchTranslationOverrides
+} from '../../src/components/SearchI18nextProvider';
+import { StaticFilters } from '../../src/components';
+import { staticFilters, staticFiltersProps } from '../__fixtures__/data/filters';
+import { generateMockedHeadless } from '../__fixtures__/search-headless';
+
+function renderStaticFilters(
+  locale?: string,
+  translationOverrides?: SearchTranslationOverrides
+) {
+  const searcher = generateMockedHeadless({
+    filters: { static: staticFilters },
+    vertical: { verticalKey: 'vertical1' },
+    meta: { searchType: 'vertical', locale }
+  });
+
+  return render(
+    <SearchHeadlessContext.Provider value={searcher}>
+      <SearchI18nextProvider searcher={searcher} translationOverrides={translationOverrides}>
+        <StaticFilters {...staticFiltersProps} searchable={true} />
+      </SearchI18nextProvider>
+    </SearchHeadlessContext.Provider>);
+}
+
+describe('SearchI18nextProvider', () => {
+  it('Uses the default options search input label when no override is given', () => {
+    renderStaticFilters();
+
+    expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
+  });
+
+  it('Applies a filterGroupSearchInputLabel override to the options search input', async () => {
+    renderStaticFilters('es', {
+      es: { filterGroupSearchInputLabel: 'Filtrar la lista de {{title}}' }
+    });
+
+    expect(
+      await screen.findByLabelText(`Filtrar la lista de ${staticFiltersProps.title}`)
+    ).toBeDefined();
+  });
+});

From 4f361017897fb1e49ef3730f4e56a7334c2c3e94 Mon Sep 17 00:00:00 2001
From: "Snyder, Chris" <SnyC1Vv@sutterhealth.org>
Date: Thu, 30 Jul 2026 14:29:56 -0400
Subject: [PATCH 4/4] fix: let consumers restyle the hidden options search
 label and inherit facet props

The hidden label now uses customCssClasses.searchInputLabel when one is
given and falls back to sr-only, so a consumer whose stylesheet lacks
sr-only can hide it another way.

Facet props passed as undefined no longer erase the values Facets
supplies, matching what absent props do.
---
 src/components/Facets.tsx                     |  6 +++++-
 src/components/Filters/SearchInput.tsx        | 10 +++++++---
 tests/components/Facets.test.tsx              | 13 ++++++++++++
 .../components/SearchI18nextProvider.test.tsx | 20 +++++++++++++++++++
 tests/components/StaticFilters.test.tsx       | 15 ++++++++++++++
 5 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/src/components/Facets.tsx b/src/components/Facets.tsx
index 1c5d51038..5d9f2dcfb 100644
--- a/src/components/Facets.tsx
+++ b/src/components/Facets.tsx
@@ -168,7 +168,11 @@ export function Facet({
   };
   const customFacetElement = fieldIdToCustomFacetProps.get(facet.fieldId);
   if (customFacetElement) {
-    facetProps = { ...facetProps, ...customFacetElement.props };
+    // A prop passed as undefined counts as unspecified, so that values supplied by Facets are
+    // inherited instead of erased.
+    const specifiedCustomProps = Object.fromEntries(
+      Object.entries(customFacetElement.props).filter(([, value]) => value !== undefined));
+    facetProps = { ...facetProps, ...specifiedCustomProps };
     facetType = getFacetTypeFromReactElementType(
       (typeof customFacetElement.type === 'function')
         ? customFacetElement.type.name : '');
diff --git a/src/components/Filters/SearchInput.tsx b/src/components/Filters/SearchInput.tsx
index 51334f8ad..35d3bdf1e 100644
--- a/src/components/Filters/SearchInput.tsx
+++ b/src/components/Filters/SearchInput.tsx
@@ -11,7 +11,10 @@ import { useId } from '../../hooks/useId';
 export interface SearchInputProps {
   /** CSS class names applied to the input element. */
   className?: string,
-  /** CSS class names applied to the label element. */
+  /**
+   * CSS class names applied to the label element. When visuallyHiddenLabel is true, this
+   * replaces the class that hides the label.
+   */
   labelClassName?: string,
   /** {@inheritDoc FilterSearch.placeholder} */
   placeholder?: string,
@@ -22,7 +25,8 @@ export interface SearchInputProps {
    * assistive technology. Defaults to false.
    *
    * @remarks
-   * When true, labelClassName is not applied since the label is not rendered visibly.
+   * The label is hidden with Tailwind's sr-only class unless labelClassName is provided, which
+   * lets consumers whose stylesheet does not define sr-only hide it another way.
    */
   visuallyHiddenLabel?: boolean
 }
@@ -55,7 +59,7 @@ export function SearchInput(props: SearchInputProps): React.JSX.Element {
     <label
       id={labelId}
       htmlFor={inputId}
-      className={visuallyHiddenLabel ? 'sr-only' : labelClassName}
+      className={visuallyHiddenLabel ? props.labelClassName ?? 'sr-only' : labelClassName}
     >
       {label}
     </label>
diff --git a/tests/components/Facets.test.tsx b/tests/components/Facets.test.tsx
index 86c499886..6fc0c61a5 100644
--- a/tests/components/Facets.test.tsx
+++ b/tests/components/Facets.test.tsx
@@ -157,6 +157,19 @@ describe('Facets', () => {
     expect(screen.getByLabelText('Search Products Options')).toBeDefined();
   });
 
+  it('A facet passing the options search input label setting as undefined inherits Facets', () => {
+    render(
+      <Facets onlyRenderChildren={true} showOptionsSearchInputLabel={true}>
+        <StandardFacet
+          fieldId='products'
+          showMoreLimit={1}
+          showOptionsSearchInputLabel={undefined}
+        />
+      </Facets>);
+
+    expect(screen.getByText('Search Products Options')).not.toHaveClass('sr-only');
+  });
+
   it('A facet overrides the options search input label setting from Facets', () => {
     render(
       <Facets onlyRenderChildren={true} showOptionsSearchInputLabel={true}>
diff --git a/tests/components/SearchI18nextProvider.test.tsx b/tests/components/SearchI18nextProvider.test.tsx
index 8518edfbd..85dd13d19 100644
--- a/tests/components/SearchI18nextProvider.test.tsx
+++ b/tests/components/SearchI18nextProvider.test.tsx
@@ -8,6 +8,12 @@ import {
 import { StaticFilters } from '../../src/components';
 import { staticFilters, staticFiltersProps } from '../__fixtures__/data/filters';
 import { generateMockedHeadless } from '../__fixtures__/search-headless';
+import { i18nInstance } from '../../src/utils';
+
+const NAMESPACE = 'search-ui-react';
+const LABEL_KEY = 'filterGroupSearchInputLabel';
+const originalEsLabel: string =
+  i18nInstance.getResource('es', NAMESPACE, LABEL_KEY);
 
 function renderStaticFilters(
   locale?: string,
@@ -28,6 +34,14 @@ function renderStaticFilters(
 }
 
 describe('SearchI18nextProvider', () => {
+  // Overrides are added to a module scoped i18next instance, so undo them to keep tests
+  // independent of the order they run in.
+  afterEach(async () => {
+    i18nInstance.addResourceBundle(
+      'es', NAMESPACE, { [LABEL_KEY]: originalEsLabel }, true, true);
+    await i18nInstance.changeLanguage('en');
+  });
+
   it('Uses the default options search input label when no override is given', () => {
     renderStaticFilters();
 
@@ -43,4 +57,10 @@ describe('SearchI18nextProvider', () => {
       await screen.findByLabelText(`Filtrar la lista de ${staticFiltersProps.title}`)
     ).toBeDefined();
   });
+
+  it('Restores the default label once an override is undone', () => {
+    renderStaticFilters();
+
+    expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
+  });
 });
diff --git a/tests/components/StaticFilters.test.tsx b/tests/components/StaticFilters.test.tsx
index a091277eb..4b9613ad6 100644
--- a/tests/components/StaticFilters.test.tsx
+++ b/tests/components/StaticFilters.test.tsx
@@ -195,6 +195,21 @@ describe('Static Filters', () => {
     expect(screen.getByLabelText(`Search ${staticFiltersProps.title} Options`)).toBeDefined();
   });
 
+  it('Uses the searchInputLabel class in place of sr-only on a hidden label', () => {
+    render(
+      <StaticFilters
+        {...staticFiltersProps}
+        searchable={true}
+        // eslint-disable-next-line react-perf/jsx-no-new-object-as-prop
+        customCssClasses={{ searchInputLabel: 'custom-hidden' }}
+      />
+    );
+
+    const label = screen.getByText(`Search ${staticFiltersProps.title} Options`);
+    expect(label).toHaveClass('custom-hidden');
+    expect(label).not.toHaveClass('sr-only');
+  });
+
   it('Keeps the search input first in its container when the label is visually hidden', () => {
     render(<StaticFilters {...staticFiltersProps} searchable={true} />);