Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Material UI Select without an initial value warns about an out-of-range value

ErrorMUI: You have provided an out-of-range value `undefined` for the select component.

Short answer

MUI Select compares its value with the value of each MenuItem. The only value it accepts without a match is an empty string, so useState() or null as the start value triggers the out-of-range warning. A multiple select needs an array, and a value that arrives before the options exist warns too. Start with '' or [] and keep types equal.

  • Applies to @mui/material 7, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the value inside the backticks of the warning. undefined or null points at the state you start with, a number or text points at a value with no matching item, and the multiple message names an array problem.

    // temporary, next to the Select
    console.log('select value:', JSON.stringify(value), typeof value);
  2. 2Match what you see, then jump to its fix

    1. 1MUI: You have provided an out-of-range value `undefined` for the select component.The state starts as undefined or nullFix
    2. 2MUI: The `value` prop must be an array when using the `Select` component with `multiple`.A multiple Select was given a stringFix
    3. 3MUI: You have provided an out-of-range value `3` for the select component., followed by the available valuesThe value has no matching MenuItem yet, or differs in textFix

What does the error look like?

  • MUI: You have provided an out-of-range value `undefined` for the select component.
  • Consider providing a value that matches one of the available options or ''.
  • MUI: The `value` prop must be an array when using the `Select` component with `multiple`.

Cause 1 of 3

The state starts as undefined or null

1Check

The warning runs when the value is not an empty string and no child matches it. Only the exact empty string is exempt, so undefined and null both trigger it. A useState() call with no argument, or an object field that is not loaded yet, produces exactly that.

grep -rn "useState()" src

2Fix

Start with an empty string, which MUI documents as the way to select no option. For a value that comes from an API, fall back to the empty string at the point of use.

const [age, setAge] = useState('');

<FormControl fullWidth>
  <InputLabel id="age-label">Age</InputLabel>
  <Select
    labelId="age-label"
    id="age"
    value={age}
    label="Age"
    onChange={(e) => setAge(e.target.value)}
  >
    <MenuItem value={10}>Ten</MenuItem>
    <MenuItem value={20}>Twenty</MenuItem>
  </Select>
</FormControl>

// value loaded from an API
value={user.age ?? ''}

3Verify

Reload the page with the console open. The warning is gone and the Select shows no selection until the user picks one.

console.log(JSON.stringify(age));

Confirmed by mui.com

Did this fix it?

Cause 2 of 3

A multiple Select was given a string

1Check

With the multiple prop the value has to be an array. This one is thrown as an error in the component, not only logged as a warning.

grep -rn "multiple" src

2Fix

Start with an empty array and keep it an array in the change handler.

const [tags, setTags] = useState([]);

<Select
  multiple
  value={tags}
  onChange={(e) => setTags(e.target.value)}
>
  <MenuItem value="red">Red</MenuItem>
  <MenuItem value="blue">Blue</MenuItem>
</Select>

3Verify

Open the page again. The Select renders and each pick adds to the array.

console.log(Array.isArray(tags));

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The value has no matching MenuItem yet, or differs in text

1Check

A value that is not an object must have the same string form as the value of one of the items. The warning also lists the available values, so compare the two lists. The usual causes are options that load after the value, an id that no longer exists in the list, or text that differs, such as "03" against 3.

console.log('value:', JSON.stringify(value));
console.log('options:', JSON.stringify(options.map((o) => o.value)));

2Fix

Show the empty string until the options exist, or fall back to it when nothing matches.

const safeValue = options.some((o) => String(o.value) === String(value)) ? value : '';

<Select value={safeValue} onChange={onChange}>
  {options.map((o) => (
    <MenuItem key={o.value} value={o.value}>{o.label}</MenuItem>
  ))}
</Select>

3Verify

Reload with slow network throttling on. The warning stays quiet while the options load.

console.log(JSON.stringify(safeValue));

Confirmed by mui.com

Did this fix it?

How do I stop it coming back?

  • Initialise every Select with '' (single) or [] (multiple), never with undefined or null.
  • Keep the text of the value identical to the text of an item value, and compare them as strings when you build a fallback.
  • When values load from a server, derive the Select value with a fallback to '' instead of passing the raw field.
  • Read the available values the warning lists before you guess what is wrong.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.