backend/flags.py

@@ -50,6 +50,13 @@ REGISTRY: dict[str, Flag] = {
             ),
             added=date(2026, 8, 23),
         ),
+        Flag(
+            name="school_autosuggest",
+            description=(
+                "School name suggestions as you type in the main search box."
+            ),
+            added=date(2026, 8, 26),
+        ),
     )
 }
 

nextjs-app/__tests__/components/FilterBarSuggest.test.tsx

@@ -0,0 +1,76 @@
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FilterBar } from '@/components/FilterBar';
+
+const push = jest.fn();
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push, replace: jest.fn(), prefetch: jest.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+const FILTERS = {
+  local_authorities: [], school_types: [], years: [], phases: [],
+  genders: [], admissions_policies: [],
+};
+
+const realFetch = global.fetch;
+beforeEach(() => {
+  global.fetch = jest.fn(async () => ({
+    ok: true,
+    json: async () => ({ suggestions: [{
+      urn: 100010, school_name: 'Brecknock Primary School',
+      local_authority: 'Camden', postcode: 'NW1 1AA',
+      phase: 'Primary', school_type: 'Community school' }] }),
+  })) as unknown as typeof fetch;
+  push.mockClear();
+});
+afterEach(() => { global.fetch = realFetch; });
+
+describe('FilterBar autosuggest', () => {
+  it('is a combobox only when the flag is on', () => {
+    const { rerender } = render(<FilterBar filters={FILTERS} autosuggest={false} />);
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+    rerender(<FilterBar filters={FILTERS} autosuggest />);
+    expect(screen.getByRole('combobox')).toBeInTheDocument();
+  });
+
+  it('makes no request while the flag is off', async () => {
+    // Off means off: no listener, no fetch, no markup.
+    render(<FilterBar filters={FILTERS} autosuggest={false} />);
+    await userEvent.type(screen.getByPlaceholderText(/School name or postcode/i),
+      'brecknock');
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it('shows suggestions and navigates when one is chosen', async () => {
+    render(<FilterBar filters={FILTERS} autosuggest />);
+    await userEvent.type(screen.getByRole('combobox'), 'brecknock');
+    const option = await screen.findByRole('option', { name: /Brecknock/ });
+    await userEvent.click(option);
+    expect(push).toHaveBeenCalledWith(
+      expect.stringContaining('/school/100010'));
+  });
+
+  it('suppresses suggestions once the value is a postcode', async () => {
+    // The box takes a name OR a postcode; suggestions must get out of the way.
+    //
+    // fireEvent.change, not userEvent.type: typing sets "N", "NW", "NW1"... and
+    // "NW1" is not a postcode, so a request for it is correct behaviour. Only
+    // the settled value is the assertion, so set it in one go.
+    render(<FilterBar filters={FILTERS} autosuggest />);
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'NW1 1AA' } });
+    await new Promise((r) => setTimeout(r, 300));   // past the 200ms debounce
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it('Enter with no active option still submits the free-text search', async () => {
+    // The existing behaviour is preserved, not replaced.
+    render(<FilterBar filters={FILTERS} autosuggest />);
+    const input = screen.getByRole('combobox');
+    await userEvent.type(input, 'brecknock{Enter}');
+    // updateURL pushes inside startTransition, so the call is not synchronous.
+    await waitFor(() => expect(push).toHaveBeenCalledWith(
+      expect.stringContaining('search=brecknock')));
+  });
+});

nextjs-app/app/page.tsx

@@ -8,6 +8,7 @@ import type { Metadata } from 'next';
 import { fetchSchools, fetchFilters, fetchDataInfo } from '@/lib/api';
 import { formatAcademicYear } from '@/lib/utils';
 import { HomeView } from '@/components/HomeView';
+import { getFlags } from '@/lib/flags';
 import { HowItWorksSection } from '@/components/HowItWorksSection';
 import { EditorialSection } from '@/components/EditorialSection';
 
@@ -63,6 +64,11 @@ export default async function HomePage({ searchParams }: HomePageProps) {
   // Await search params (Next.js 15 requirement)
   const params = await searchParams;
 
+  // Server-read: no flag value reaches the browser bundle. Threaded down to
+  // both FilterBar instances via HomeView.
+  const flags = await getFlags();
+  const autosuggest = flags.school_autosuggest === true;
+
   // Parse search params
   const page = parseInt(params.page || '1');
   const radius = params.radius ? parseFloat(params.radius) : undefined;
@@ -111,6 +117,7 @@ export default async function HomePage({ searchParams }: HomePageProps) {
     const years = dataInfo?.years_available ?? [];
     return (
       <HomeView
+        autosuggest={autosuggest}
         initialSchools={schoolsData}
         filters={resolvedFilters}
         totalSchools={total}
@@ -131,6 +138,7 @@ export default async function HomePage({ searchParams }: HomePageProps) {
     const emptyFilters = { local_authorities: [], school_types: [], years: [], phases: [], genders: [], admissions_policies: [] };
     return (
       <HomeView
+        autosuggest={autosuggest}
         initialSchools={{ schools: [], page: 1, page_size: 50, total: 0, total_pages: 0 }}
         filters={emptyFilters}
         totalSchools={null}

nextjs-app/components/FilterBar.module.css

@@ -48,6 +48,8 @@
   display: flex;
   align-items: center;
   gap: 0.5rem;
+  /* The suggestion dropdown is absolutely positioned against this box. */
+  position: relative;
 }
 
 /* The hero pill: hairline, soft corner, everything else sits inside it. */

nextjs-app/components/FilterBar.tsx

@@ -3,8 +3,11 @@
 import { useState, useCallback, useTransition, useRef, useEffect } from "react";
 import type { ReactNode } from "react";
 import { useRouter, useSearchParams, usePathname } from "next/navigation";
-import { isValidPostcode } from "@/lib/utils";
+import { isValidPostcode, schoolUrl } from "@/lib/utils";
 import { track } from "@/lib/analytics";
+import { useSchoolSuggest } from "@/hooks/useSchoolSuggest";
+import { SuggestList, suggestOptionId } from "./SuggestList";
+import type { Suggestion } from "@/lib/suggest";
 import type { Filters, ResultFilters } from "@/lib/types";
 import styles from "./FilterBar.module.css";
 
@@ -17,6 +20,8 @@ interface FilterBarProps {
   onNearMe?: () => void;
   geoState?: "idle" | "requesting" | "error";
   geoError?: string | null;
+  /** Server-read feature flag. Off means no listener, no fetch, no markup. */
+  autosuggest?: boolean;
 }
 
 /**
@@ -48,6 +53,7 @@ export function FilterBar({
   onNearMe,
   geoState = "idle",
   geoError,
+  autosuggest = false,
 }: FilterBarProps) {
   const router = useRouter();
   const pathname = usePathname();
@@ -62,6 +68,45 @@ export function FilterBar({
 
   const [omniValue, setOmniValue] = useState(initialOmniValue);
 
+  const suggestId = `school-suggest-${isHero ? "hero" : "bar"}`;
+  // Suppressed once the value parses as a postcode: the box takes a school
+  // name OR a postcode, and suggesting schools during postcode entry fights
+  // the user rather than helping them.
+  const suggestEnabled = autosuggest && !isValidPostcode(omniValue);
+  const { suggestions, open, activeIndex, setActiveIndex, close } =
+    useSchoolSuggest(omniValue, suggestEnabled);
+
+  const pickSuggestion = (s: Suggestion) => {
+    close();
+    track('search_submitted', {
+      query: s.school_name.toLowerCase(),
+      via: 'suggestion',
+      urn: s.urn,
+      has_postcode: false,
+      filters_active: '',
+      filters_count: 0,
+    });
+    router.push(schoolUrl(s.urn, s.school_name));
+  };
+
+  const handleOmniKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (!open) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActiveIndex(activeIndex + 1 >= suggestions.length ? 0 : activeIndex + 1);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex(activeIndex <= 0 ? suggestions.length - 1 : activeIndex - 1);
+    } else if (e.key === "Escape") {
+      close();
+    } else if (e.key === "Enter" && activeIndex >= 0) {
+      // Only when an option is active. With none, the event falls through to
+      // the form's submit handler and searches the typed text, as it does now.
+      e.preventDefault();
+      pickSuggestion(suggestions[activeIndex]);
+    }
+  };
+
   const currentLA = searchParams.get("local_authority") || "";
   const currentType = searchParams.get("school_type") || "";
   const currentPhase = searchParams.get("phase") || "";
@@ -227,8 +272,19 @@ export function FilterBar({
             type="search"
             value={omniValue}
             onChange={(e) => setOmniValue(e.target.value)}
+            onKeyDown={handleOmniKeyDown}
+            onBlur={close}
             placeholder="School name or postcode"
             className={styles.omniInput}
+            {...(autosuggest ? {
+              role: "combobox",
+              "aria-expanded": open,
+              "aria-controls": suggestId,
+              "aria-autocomplete": "list" as const,
+              "aria-activedescendant":
+                activeIndex >= 0 ? suggestOptionId(suggestId, activeIndex) : undefined,
+              autoComplete: "off",
+            } : {})}
           />
           <button
             type="submit"
@@ -237,6 +293,15 @@ export function FilterBar({
           >
             {isPending ? <div className={styles.spinner}></div> : isHero ? "Search schools" : "Search"}
           </button>
+          {autosuggest && open && (
+            <SuggestList
+              id={suggestId}
+              suggestions={suggestions}
+              activeIndex={activeIndex}
+              onPick={pickSuggestion}
+              onHover={setActiveIndex}
+            />
+          )}
         </div>
         {isHero && (
           <>

nextjs-app/components/HomeView.tsx

@@ -29,6 +29,8 @@ interface HomeViewProps {
   // show (e.g. an active search).
   howItWorks?: React.ReactNode;
   editorial?: React.ReactNode;
+  /** Server-read feature flag, threaded to both FilterBar instances. */
+  autosuggest?: boolean;
 }
 
 function daysUntil(month: number, day: number): number {
@@ -193,7 +195,7 @@ const VALUE_PROPS: ValueProp[] = [
   },
 ];
 
-export function HomeView({ initialSchools, filters, totalSchools, howItWorks, editorial }: HomeViewProps) {
+export function HomeView({ initialSchools, filters, totalSchools, howItWorks, editorial, autosuggest = false }: HomeViewProps) {
   const searchParams = useSearchParams();
   const router = useRouter();
   const pathname = usePathname();
@@ -462,6 +464,7 @@ export function HomeView({ initialSchools, filters, totalSchools, howItWorks, ed
               onNearMe={handleNearMe}
               geoState={geoState}
               geoError={geoError}
+              autosuggest={autosuggest}
             />
           </div>
 
@@ -500,6 +503,7 @@ export function HomeView({ initialSchools, filters, totalSchools, howItWorks, ed
           onNearMe={handleNearMe}
           geoState={geoState}
           geoError={geoError}
+          autosuggest={autosuggest}
         />
       )}