Skip to main content

ReferenceInput

** Last Built**: September 2, 2025 at 4:19 PM A form input component for handling references to other resources. This component allows users to select values from a referenced resource, supporting both single and multiple selections with optional search functionality.

Basic Usage​

import { ReferenceInput } from 'react-superadmin';
function MyForm() {
  const [author, setAuthor] = useState(null);
  return (
    <ReferenceInput
  name='author'
  label='Author'
  reference='authors'
  optionText='name'
  optionValue='id'
  value={author}
  onChange={setAuthor}
  dataProvider={myDataProvider}
    />
  );
}

Props​

| Prop | Type | Default | Description | | ------------------------------------------------- | | name | string | - | The name of the field | | label | string | - | The label to display | | reference | string | - | The resource to reference | | optionText | string | "name" | The field to display from the referenced resource | | optionValue | string | "id" | The field to use as the value | | multiple | boolean | false | Whether to allow multiple selections | | required | boolean | false | Whether the field is required | | disabled | boolean | false | Whether the field is disabled | | hidden | boolean | false | Whether to show the field | | value | any | - | The current value | | onChange | (value: any) => void | - | Callback when the value changes | | placeholder | string | - | The placeholder text | | searchable | boolean | true | Whether to show a search input | | autocomplete | boolean | false | Whether to use autocomplete mode | | dataProvider | (resource: string, params: any) => Promise<any> | - | The data provider function | | filter | any | - | The filter to apply to the reference data | | sort | any | - | The sort to apply to the reference data | | pagination | any | - | The pagination to apply to the reference data | | size | "sm" \| "md" \| "lg" | "md" | The size variant | | errors | string[] | [] | The validation errors | | touched | boolean | false | The touched state | | showValidationErrors | boolean | true | Whether to show validation errors |

Examples​

Single Selection​

Multiple Selection​

Autocomplete Mode​

With Validation​

Category is required

With Custom Filtering​

Data Provider Integration​

The ReferenceInput component integrates with data providers to fetch reference data. The data provider should implement the getList method:

const dataProvider = async (resource, method, params) => {
  if (method === 'getList') {
    // Fetch data from your API
    const response = await fetch(`/api/${resource}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(params),
    });
    const data = await response.json();
    return {
  data: data.items,
  total: data.total,
    };
  }
};

Customization​

Styling​

You can customize the appearance using CSS classes:

<ReferenceInput
  name='author'
  label='Author'
  reference='authors'
  className='custom-reference'
  labelClassName='custom-label'
  inputClassName='custom-input'
  errorClassName='custom-error'
  helperClassName='custom-helper'
  dataProvider={myDataProvider}
/>

Size Variants​

The component supports three size variants:

// Small
<ReferenceInput size="sm" {...props} />
// Medium (default)
<ReferenceInput size="md" {...props} />
// Large
<ReferenceInput size="lg" {...props} />

Accessibility​

The ReferenceInput component includes comprehensive accessibility features:

  • Proper ARIA labels and descriptions
  • Keyboard navigation support
  • Screen reader compatibility
  • Focus management
  • Error announcement

Integration with Forms​

The ReferenceInput component integrates seamlessly with form libraries like React Hook Form:

import { useForm } from 'react-hook-form';
function MyForm() {
  const { register, handleSubmit, setValue, watch } = useForm();
  const author = watch('author');
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
  <ReferenceInput
  name='author'
  label='Author'
  reference='authors'
  value={author}
  onChange={value => setValue('author', value)}
  dataProvider={myDataProvider}
  />
  <button type='submit'>Submit</button>
    </form>
  );
}

Error Handling​

The component handles various error scenarios:

  • Network errors during data fetching
  • Validation errors
  • Missing data provider
  • Empty reference data
<ReferenceInput
  name='author'
  label='Author'
  reference='authors'
  errors={['Author is required']}
  touched
  dataProvider={myDataProvider}
/>

Performance Considerations​

  • The component loads reference data on mount
  • Search functionality is debounced in autocomplete mode
  • Options are cached to avoid unnecessary API calls
  • Pagination is supported for large datasets

Best Practices​

  1. Use meaningful optionText and optionValue: Choose fields that make sense for your use case
  2. Implement proper error handling: Handle network errors and validation errors gracefully
  3. Optimize data provider calls: Use caching and pagination for large datasets
  4. Provide clear labels and placeholders: Help users understand what they're selecting
  5. Test accessibility: Ensure the component works with screen readers and keyboard navigation