Select

The select component allows users to make single or multiple selections from a pre-defined list of options.

Props

Name	Type	Description	Default
defaultValue	`string \| string[]`	Initial value of the select, only when it is uncontrolled.	-
value	`string \| string[]`	Value of the select. If undefined, the component will be uncontrolled and the value will be managed internally by the component.	-
label	`string`	Text to be placed above the select.	-
name	`string`	Name attribute of the input element. This attribute will allow users to find the component's value during the submit event. In this event, the component's value will always be a regular string, for both single and multiple selection modes, being a single option value in the first case and more than one value when multiple selection is available, separated by commas.	-
Required options	`({ label: string, value: string, icon: (string \| React.ReactNode & React.SVGProps <SVGSVGElement>) })[] \| ({ label: string, options: Option[] })[]`	An array of objects representing the selectable options. Each object has the following properties depending on whether it is a regular option or a group: Option label: Label of the option to be shown in the select's listbox. value: Value of the option. It should be unique and not an empty string, which is reserved to the empty option added by `optional` prop. icon: Material Symbol name or SVG element used as the icon for the option. When using Material Symbols, replace spaces with underscores. By default they are outlined if you want it to be filled prefix the symbol name with `"filled_"`. Grouped options label: Label of the group to be shown in the select's listbox. options: List of `Option` instances.	-
helperText	`string`	Helper text to be placed above the select.	-
placeholder	`string`	Text to be put as placeholder of the select.	-
searchable	`boolean`	If true, enables search functionality.	`false`
multiple	`boolean`	If true, the select component will support multiple selected options. In that case, value will be an array of strings with each selected option value.	`false`
disabled	`boolean`	If true, the component will be disabled.	`false`
optional	`boolean`	If true, the select will be optional, showing '(Optional)' next to the label and adding a default first option with an empty string as value and the placeholder (if defined) as its label. Otherwise, the field will be considered required and an error will be passed as a parameter to the `onBlur` and `onChange` functions if an option wasn't selected.	`false`
onChange	`(val: { value: string \| string[]; error?: string }) => void`	This function will be called when the user selects an option. An object including the new value (or values) and the error (if the value selected is not valid) will be passed to this function. If there is no error, `error` will not be defined.	-
onBlur	`(val: { value: string \| string[]; error?: string }) => void`	This function will be called when the select loses the focus. An object including the value (or values) and the error (if the value selected is not valid) will be passed to this function. If there is no error, `error` will not be defined.	-
error	`string`	If it is a defined value and also a truthy string, the component will change its appearance, showing the error below the select component. If the defined value is an empty string, it will reserve a space below the component for a future error, but it would not change its look. In case of being undefined or null, both the appearance and the space for the error message would not be modified.	-
margin	`'xxsmall' \| 'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge' \| 'xxlarge' \| Margin`	Size of the margin to be applied to the component. You can pass an object with 'top', 'bottom', 'left' and 'right' properties in order to specify different margin sizes.	-
size	`'small' \| 'medium' \| 'large' \| 'fillParent'`	Size of the component.	`'medium'`
tabIndex	`number`	Value of the `tabindex` attribute.	`0`
ref	`React.Ref <HTMLDivElement>`	Reference to the component.	-

Examples

Controlled

() => {
  const [value, setValue] = useState("");
  const onChange = ({ value }) => {
    setValue(value);
  };
  const onBlur = ({ value, error }) => {
    setValue(value);
  };

  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favorite city"
        placeholder="Choose a city"
        options={options}
        value={value}
        onBlur={onBlur}
        onChange={onChange}
      />
    </DxcInset>
  );
}

() => {
  const [value, setValue] = useState("");
  const onChange = ({ value }) => {
    setValue(value);
  };
  const onBlur = ({ value, error }) => {
    setValue(value);
  };

  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favorite city"
        placeholder="Choose a city"
        options={options}
        value={value}
        onBlur={onBlur}
        onChange={onChange}
      />
    </DxcInset>
  );
}

Uncontrolled

() => {
  const selectRef = useRef();
  const handleSubmit = () => {
    const select = selectRef.current.getElementsByTagName("input")[0];
    console.log(select.value);
  };
  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcFlex direction="column" gap="2rem" alignItems="flex-start">
        <DxcSelect
          label="Select your favorite city"
          placeholder="Choose a city"
          defaultValue="madrid"
          options={options}
          ref={selectRef}
        />
        <DxcButton onClick={handleSubmit} label="Submit" />
      </DxcFlex>
    </DxcInset>
  );
}

() => {
  const selectRef = useRef();
  const handleSubmit = () => {
    const select = selectRef.current.getElementsByTagName("input")[0];
    console.log(select.value);
  };
  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcFlex direction="column" gap="2rem" alignItems="flex-start">
        <DxcSelect
          label="Select your favorite city"
          placeholder="Choose a city"
          defaultValue="madrid"
          options={options}
          ref={selectRef}
        />
        <DxcButton onClick={handleSubmit} label="Submit" />
      </DxcFlex>
    </DxcInset>
  );
}

Error handling

() => {
  const [value, setValue] = useState("");
  const [error, setError] = useState();
  const onChange = ({ value }) => {
    setValue(value);
  };
  const onBlur = ({ value, error }) => {
    setValue(value);
    setError(error);
  };

  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favorite city"
        placeholder="Choose a city"
        options={options}
        value={value}
        onBlur={onBlur}
        onChange={onChange}
        error={error == undefined ? "" : error}
      />
    </DxcInset>
  );
}

() => {
  const [value, setValue] = useState("");
  const [error, setError] = useState();
  const onChange = ({ value }) => {
    setValue(value);
  };
  const onBlur = ({ value, error }) => {
    setValue(value);
    setError(error);
  };

  const options = [
    { label: "Madrid", value: "madrid" },
    { label: "Melbourne", value: "melbourne" },
    { label: "London", value: "london" },
    { label: "Roma", value: "roma" },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favorite city"
        placeholder="Choose a city"
        options={options}
        value={value}
        onBlur={onBlur}
        onChange={onChange}
        error={error == undefined ? "" : error}
      />
    </DxcInset>
  );
}

Grouped options

() => {
  const options = [
    {
      label: "Managers",
      options: [
        { label: "Pablo", value: "pablo" },
        { label: "Marcos", value: "marcos" },
        { label: "Rachel", value: "rachel" },
        { label: "Margaret", value: "margaret" },
      ],
    },
    {
      label: "Engineers",
      options: [
        { label: "Yiminghe", value: "yiminghe" },
        { label: "Manuel", value: "manuel" },
        { label: "Bryan", value: "bryan" },
        { label: "Anand", value: "anand" },
        { label: "Jiale", value: "jiale" },
      ],
    },
    {
      label: "Designers",
      options: [
        { label: "Alex", value: "alex" },
        { label: "Tim", value: "tim" },
        { label: "Jairo", value: "Jairo" },
      ],
    },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your coworkers"
        placeholder="Choose a colleague"
        options={options}
        multiple
      />
    </DxcInset>
  );
}

() => {
  const options = [
    {
      label: "Managers",
      options: [
        { label: "Pablo", value: "pablo" },
        { label: "Marcos", value: "marcos" },
        { label: "Rachel", value: "rachel" },
        { label: "Margaret", value: "margaret" },
      ],
    },
    {
      label: "Engineers",
      options: [
        { label: "Yiminghe", value: "yiminghe" },
        { label: "Manuel", value: "manuel" },
        { label: "Bryan", value: "bryan" },
        { label: "Anand", value: "anand" },
        { label: "Jiale", value: "jiale" },
      ],
    },
    {
      label: "Designers",
      options: [
        { label: "Alex", value: "alex" },
        { label: "Tim", value: "tim" },
        { label: "Jairo", value: "Jairo" },
      ],
    },
  ];

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your coworkers"
        placeholder="Choose a colleague"
        options={options}
        multiple
      />
    </DxcInset>
  );
}

Icons

() => {
  const options_material = [
    {
      label: "Transport",
      options: [
        {
          label: "Electric Car",
          value: "car",
          icon: "electric_car",
        },
        {
          label: "Motorcycle",
          value: "motorcycle",
          icon: "Motorcycle",
        },
        {
          label: "Train",
          value: "train",
          icon: "train",
        },
        {
          label: "Bike",
          value: "bike",
          icon: "pedal_bike",
        },
      ],
    },
    {
      label: "Entertainment",
      options: [
        {
          label: "Movie",
          value: "movie",
          icon: "movie",
        },
        {
          label: "Music",
          value: "music",
          icon: "music_note",
        },
        {
          label: "Games",
          value: "games",
          icon: "joystick",
        },
      ],
    },
  ];
  
  

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favourite social media"
        placeholder="Choose an option"
        options={options_material}
      />
    </DxcInset>
  );
}

() => {
  const options_material = [
    {
      label: "Transport",
      options: [
        {
          label: "Electric Car",
          value: "car",
          icon: "electric_car",
        },
        {
          label: "Motorcycle",
          value: "motorcycle",
          icon: "Motorcycle",
        },
        {
          label: "Train",
          value: "train",
          icon: "train",
        },
        {
          label: "Bike",
          value: "bike",
          icon: "pedal_bike",
        },
      ],
    },
    {
      label: "Entertainment",
      options: [
        {
          label: "Movie",
          value: "movie",
          icon: "movie",
        },
        {
          label: "Music",
          value: "music",
          icon: "music_note",
        },
        {
          label: "Games",
          value: "games",
          icon: "joystick",
        },
      ],
    },
  ];
  
  

  return (
    <DxcInset space="2rem">
      <DxcSelect
        label="Select your favourite social media"
        placeholder="Choose an option"
        options={options_material}
      />
    </DxcInset>
  );
}

Props
Examples

Edit this page on GitHub

Report an issue on GitHub

Resultset Table

NextSidenav

Select

Props

Examples

Controlled

Uncontrolled

Error handling

Grouped options

Icons

Contents