Autocomplete

Type-ahead autocomplete built on MUI Autocomplete. Fully generic — works with any option shape via getOptionValue and getOptionLabel. Integrates with DashForm automatically.

Registration, validation, error handling, reactive visibility, and field orchestration are handled internally by the component. The component is designed for form-driven workflows involving searchable options, async data, dependent fields, and dynamic option sources. Unlike the base MUI Autocomplete, this component is optimized for integration with the Dashforge form engine rather than standalone orchestration. The name prop is required to connect the field to the form schema and the internal engine.

Quick Start

const frameworks = [
  { id: 'react', name: 'React' },
  { id: 'vue', name: 'Vue' },
];

<Autocomplete
  name="framework"
  label="Framework"
  options={frameworks}
  getOptionValue={(o) => o.id}
  getOptionLabel={(o) => o.name}
  rules={{ required: 'Required' }}
/>

API

Notes

• The stored form value is whatever getOptionValue returns, not the full option object.
• When freeSolo is true, the stored value is the raw typed string when no matching option is selected.

Capabilities

Autocomplete is designed for progressive adoption. Use it as a controlled component, integrate with React Hook Form, or load options reactively from form state.

Controlled

Autocomplete works as a standard React controlled component with familiar patterns. No proprietary lock-in required.

• Standard value and onChange props
• Always freeSolo mode for flexibility
• Easy incremental adoption

<Autocomplete
  value={country}
  onChange={(e, val) => setCountry(val)}
  options={countries}
  label="Country"
/>

React Hook Form Ready

Integration-Friendly

Designed to integrate with React Hook Form workflows through DashForm. Compatible with existing form-library patterns.

• Works through DashForm bridge
• Validation and error handling supported

<DashForm>
  <Autocomplete
    name="country"
    label="Country"
    options={countries}
  />
</DashForm>

Reactive Options

Autocomplete can load options dynamically from form state or external data. Supports mapper functions for custom option shapes.

• Runtime options via optionsFromFieldData
• Mapper functions for custom shapes
• Conditional visibility with visibleWhen

<Autocomplete
  name="city"
  label="City"
  optionsFromFieldData="cityOptions"
  getOptionValue={(opt) => opt.id}
  getOptionLabel={(opt) => opt.name}
  visibleWhen={(engine) =>
    engine.getNode('country')?.value !== ''
  }
/>

Access Control (RBAC)

Control field visibility and interaction based on user permissions. Fields can be hidden, disabled, or readonly when users lack access.

Hide when unauthorized

<Autocomplete
  name="assignee"
  label="Assignee"
  access={{
    resource: 'task.assignee',
    action: 'edit',
    onUnauthorized: 'hide'
  }}
  options={[
    { value: 'alice', label: 'Alice' },
    { value: 'bob', label: 'Bob' }
  ]}
/>

Disable when cannot edit

<Autocomplete
  name="status"
  label="Status"
  access={{
    resource: 'task.status',
    action: 'update',
    onUnauthorized: 'disable'
  }}
  options={[
    { value: 'open', label: 'Open' },
    { value: 'done', label: 'Done' }
  ]}
/>

Readonly for view-only

<Autocomplete
  name="category"
  label="Category"
  access={{
    resource: 'product.category',
    action: 'update',
    onUnauthorized: 'readonly'
  }}
  options={[
    { value: 'electronics', label: 'Electronics' },
    { value: 'books', label: 'Books' }
  ]}
/>

Combined with visibleWhen

<Autocomplete
  name="expediteReason"
  label="Expedite Reason"
  visibleWhen={(e) =>
    e.getValue('type') === 'expedited'
  }
  access={{
    resource: 'order.expedite',
    action: 'edit',
    onUnauthorized: 'readonly'
  }}
  options={[
    { value: 'urgent', label: 'Urgent' }
  ]}
/>

Scenarios

Common real-world patterns showing Autocomplete in context.

Form Validation

Integrate with DashForm for validation, error handling, and form submission. Shows required fields and custom validation rules.

<DashForm onSubmit={handleSubmit}>
  <Autocomplete
    name="country"
    label="Country"
    options={countries}
    rules={{ required: 'Country is required' }}
    fullWidth
  />
  <Autocomplete
    name="city"
    label="City"
    options={cities}
    rules={{
      required: 'City is required',
      validate: (value) => {
        if (value && value.length < 3) {
          return 'City must be at least 3 characters';
        }
        return true;
      },
    }}
    fullWidth
  />
  <Button type="submit" variant="contained">Submit</Button>
</DashForm>

Runtime Dependent Options

Options that change based on another field's value. Uses optionsFromFieldData to load options from runtime state. The dependent field value is not reset when options change.

<DashForm
  reactions={[
    {
      id: 'update-subcategory-options',
      watch: ['category'],
      run: ({ getValue, setRuntime }) => {
        const category = getValue('category');
        const subcategories = getSubcategoriesForCategory(category);
        setRuntime('subcategory', {
          status: 'ready',
          data: { options: subcategories },
        });
      },
    },
  ]}
>
  <Autocomplete name="category" label="Category" options={categories} />
  <Autocomplete
    name="subcategory"
    label="Subcategory"
    options={[]}
    optionsFromFieldData
  />
</DashForm>