SGERP Autocomplete

Prerequisites

This component requires sgerp-frontend-lib to be installed in your project. See the Installation guide for setup instructions.

Dependencies

This component will automatically install:

lucide-react - For icons
shadcn/ui components: button, input

Usage

import { SGERPAutocomplete } from "@/components/ui/sgerp-autocomplete"

export function MyComponent() {
  const [selectedId, setSelectedId] = useState<number | null>(null)

  return (
    <SGERPAutocomplete
      collectionName="project"
      onSelectionChange={setSelectedId}
      renderLabel={(project) => project.name}
      placeholder="Search projects..."
    />
  )
}

Props

Prop	Type	Description
`collectionName`	`"project" \| "user" \| "simulation" \| "vehicle" \| "vehicletype" \| "booking" \| "node" \| "projectmember"`	The SGERP collection to search
`onSelectionChange`	`(value: number \| null, object?: any) => void`	Callback when selection changes. Receives both the ID and the full object
`renderLabel`	`(item: any) => string`	Optional. Function to render item labels. Defaults to `name` or `#id`
`placeholder`	`string`	Optional. Input placeholder text. Default: "Search..."
`className`	`string`	Optional. Additional CSS classes
`filters`	`Record<string, any>`	Optional. Additional query filters to apply (e.g., `{ project_id: 123, simulation_mode: 'template' }`)
`disabled`	`boolean`	Optional. Disables the autocomplete. Default: false
`language`	`"en" \| "ja"`	Optional. Language for UI messages. Defaults to "en"
`value`	`number \| null`	Optional. Controlled value for the selected item ID. Makes the component controlled

Features

Debounced Search: 300ms debounce on input changes
Keyboard Navigation: Arrow keys to navigate, Enter to select, Escape to close
Loading States: Shows loading indicator while fetching
Selection Display: Selected item shown as a chip with remove button
Auto-scroll: Highlighted item auto-scrolls into view
Responsive: Works on all screen sizes
Custom Filters: Apply additional query filters for dependent dropdowns
Conditional Disable: Disable autocomplete based on external conditions
Localization: Supports English and Japanese UI messages

Examples

Basic Usage

<SGERPAutocomplete
  collectionName="project"
  onSelectionChange={(id) => console.log("Selected project:", id)}
/>

Custom Label Rendering

<SGERPAutocomplete
  collectionName="user"
  onSelectionChange={setUserId}
  renderLabel={(user) => `${user.first_name} ${user.last_name} (${user.email})`}
  placeholder="Search users..."
/>

With Custom Styling

<SGERPAutocomplete
  collectionName="simulation"
  onSelectionChange={setSimulationId}
  renderLabel={(sim) => `${sim.name} - ${sim.status}`}
  className="max-w-md"
/>

Dependent Autocompletes with Filters

const [projectId, setProjectId] = useState<number | null>(null);
const [templateId, setTemplateId] = useState<number | null>(null);

return (
  <>
    {/* First: Select a project */}
    <SGERPAutocomplete
      collectionName="project"
      onSelectionChange={setProjectId}
      renderLabel={(project) => project.name}
      placeholder="Select a project..."
    />

    {/* Second: Select a template filtered by project_id and simulation_mode */}
    <SGERPAutocomplete
      collectionName="simulation"
      onSelectionChange={setTemplateId}
      renderLabel={(sim) => sim.name}
      placeholder={projectId ? "Select a template..." : "Select a project first"}
      disabled={!projectId}
      filters={projectId ? { project_id: projectId, simulation_mode: 'template' } : {}}
    />
  </>
);

Using the Full Object from Selection

The callback receives both the ID and the full object, useful when you need additional properties:

const [projectId, setProjectId] = useState<number | null>(null);
const [projectTimezone, setProjectTimezone] = useState<string>('UTC');

return (
  <SGERPAutocomplete
    collectionName="project"
    onSelectionChange={(id, project) => {
      setProjectId(id);
      if (project) {
        setProjectTimezone(project.timezone || 'UTC');
      }
    }}
    renderLabel={(project) => project.name}
    placeholder="Select a project..."
  />
);

Controlled Component with Value Prop

Use the value prop to externally control the selected item (e.g., for auto-selection):

const [selectedProjectId, setSelectedProjectId] = useState<number | null>(null);

// Auto-select a project programmatically
useEffect(() => {
  // When only one project exists, auto-select it
  if (projects.length === 1) {
    setSelectedProjectId(projects[0].id);
  }
}, [projects]);

return (
  <SGERPAutocomplete
    collectionName="project"
    value={selectedProjectId}
    onSelectionChange={(id) => setSelectedProjectId(id)}
    renderLabel={(project) => project.name}
    placeholder="Select a project..."
  />
);

Form Integration

import { SGERPAutocomplete } from "@/components/sgerp-autocomplete"
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import * as z from "zod"

const formSchema = z.object({
  projectId: z.number().min(1, "Project is required"),
})

export function MyForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
  })

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <div>
        <label>Project</label>
        <SGERPAutocomplete
          collectionName="project"
          onSelectionChange={(id) => form.setValue("projectId", id ?? 0)}
        />
        {form.formState.errors.projectId && (
          <p className="text-sm text-destructive">
            {form.formState.errors.projectId.message}
          </p>
        )}
      </div>
    </form>
  )
}

Keyboard Shortcuts

Key	Action
`↓`	Move to next suggestion
`↑`	Move to previous suggestion
`Enter`	Select highlighted suggestion
`Escape`	Close suggestions and blur input

API Integration

The component uses the useSGERP() hook to access collections and automatically:

Fetches data with a 20-item limit
Filters by name__icontains when searching
Handles loading and error states
Requires an active SGERP connection

Make sure you have set up a connection before using this component. See the Try It Out page for connection setup.

Project Autocomplete

Dependent Autocomplete