Nota bene

Questa pagina è stata tradotta automaticamente e supervisionata da un maintainer. Un’ulteriore revisione da parte della community sarebbe comunque utile. Migliora questa traduzione.

Il componente browser integrato <select> ti permette di renderizzare una casella select con opzioni.

<select>
  <option value="someOption">Some option</option>
  <option value="otherOption">Other option</option>
</select>

Reference

<select>

Per visualizzare una casella select, renderizza il componente browser integrato <select>.

<select>
  <option value="someOption">Some option</option>
  <option value="otherOption">Other option</option>
</select>

Vedi altri esempi sotto.

Props

<select> supporta tutte le props comuni degli elementi.

Puoi controllare una casella select passando una prop value:

  • value: Una stringa (o un array di stringhe per multiple={true}). Controlla quale opzione è selezionata. Ogni stringa del valore deve corrispondere al value di un <option> annidato dentro il <select>.

Quando passi value, devi anche passare un gestore di eventi onChange che aggiorni il valore passato.

Se il tuo <select> è non controllato, puoi passare invece la prop defaultValue:

Queste props di <select> sono rilevanti sia per caselle select non controllate che controllate:

  • autoComplete: Una stringa. Specifica uno dei possibili comportamenti di autocomplete.
  • autoFocus: Un booleano. Se true, React metterà a fuoco l’elemento al montaggio.
  • children: <select> accetta come children i componenti <option>, <optgroup> e <datalist>. Puoi anche passare i tuoi componenti, purché alla fine renderizzino uno dei componenti consentiti. Se passi i tuoi componenti che alla fine renderizzano tag <option>, ogni <option> che renderizzi deve avere un value.
  • disabled: Un booleano. Se true, la casella select non sarà interattiva e apparirà attenuata.
  • form: Una stringa. Specifica l’id del <form> a cui appartiene questa casella select. Se omesso, è il form padre più vicino.
  • multiple: Un booleano. Se true, il browser consente la selezione multipla.
  • name: Una stringa. Specifica il nome di questa casella select che viene inviato con il form.
  • onChange: Una funzione gestore di Event. Obbligatorio per caselle select controllate. Scatta immediatamente quando l’utente sceglie un’opzione diversa. Si comporta come l’evento input del browser.
  • onChangeCapture: Una versione di onChange che scatta nella fase di capture.
  • onInput: Una funzione gestore di Event. Scatta immediatamente quando il valore viene modificato dall’utente. Per ragioni storiche, in React è idiomatico usare onChange al suo posto, che funziona in modo simile.
  • onInputCapture: Una versione di onInput che scatta nella fase di capture.
  • onInvalid: Una funzione gestore di Event. Scatta se un input non supera la validazione all’invio del form. A differenza dell’evento invalid integrato, l’evento React onInvalid fa bubbling.
  • onInvalidCapture: Una versione di onInvalid che scatta nella fase di capture.
  • required: Un booleano. Se true, il valore deve essere fornito affinché il form possa essere inviato.
  • size: Un numero. Per select con multiple={true}, specifica il numero preferito di elementi inizialmente visibili.

Caveats

  • A differenza dell’HTML, passare un attributo selected a <option> non è supportato. Usa invece <select defaultValue> per caselle select non controllate e <select value> per caselle select controllate.
  • Se una casella select riceve una prop value, verrà trattata come controllata.
  • Una casella select non può essere contemporaneamente controllata e non controllata.
  • Una casella select non può passare da controllata a non controllata (o viceversa) nel corso della sua vita.
  • Ogni casella select controllata necessita di un gestore di eventi onChange che aggiorni in modo sincrono il valore sottostante.

Usage

Visualizzare una casella di selezione con opzioni

Renderizza un <select> con un elenco di componenti <option> al suo interno per visualizzare una casella select. Assegna a ogni <option> un value che rappresenta i dati da inviare con il form.

export default function FruitPicker() {
  return (
    <label>
      Pick a fruit:
      <select name="selectedFruit">
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
      </select>
    </label>
  );
}

Fornire un’etichetta per una casella di selezione

Di solito, posizionerai ogni <select> dentro un tag <label>. Questo indica al browser che questa etichetta è associata a quella casella select. Quando l’utente clicca sull’etichetta, il browser metterà automaticamente a fuoco la casella select. È anche essenziale per l’accessibilità: uno screen reader annuncerà la didascalia dell’etichetta quando l’utente mette a fuoco la casella select.

Se non puoi annidare <select> dentro un <label>, associali passando lo stesso ID a <select id> e <label htmlFor>. Per evitare conflitti tra più istanze dello stesso componente, genera un ID del genere con useId.

import { useId } from 'react';

export default function Form() {
  const vegetableSelectId = useId();
  return (
    <>
      <label>
        Pick a fruit:
        <select name="selectedFruit">
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="orange">Orange</option>
        </select>
      </label>
      <hr />
      <label htmlFor={vegetableSelectId}>
        Pick a vegetable:
      </label>
      <select id={vegetableSelectId} name="selectedVegetable">
        <option value="cucumber">Cucumber</option>
        <option value="corn">Corn</option>
        <option value="tomato">Tomato</option>
      </select>
    </>
  );
}

Fornire un’opzione inizialmente selezionata

Per impostazione predefinita, il browser selezionerà il primo <option> nell’elenco. Per selezionare un’opzione diversa di default, passa il value di quell’<option> come defaultValue all’elemento <select>.

export default function FruitPicker() {
  return (
    <label>
      Pick a fruit:
      <select name="selectedFruit" defaultValue="orange">
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
      </select>
    </label>
  );
}

Insidia

A differenza dell’HTML, passare un attributo selected a un singolo <option> non è supportato.

Abilitare la selezione multipla

Passa multiple={true} al <select> per consentire all’utente di selezionare più opzioni. In quel caso, se specifichi anche defaultValue per scegliere le opzioni inizialmente selezionate, deve essere un array.

export default function FruitPicker() {
  return (
    <label>
      Pick some fruits:
      <select
        name="selectedFruit"
        defaultValue={['orange', 'banana']}
        multiple={true}
      >
        <option value="apple">Apple</option>
        <option value="banana">Banana</option>
        <option value="orange">Orange</option>
      </select>
    </label>
  );
}

Leggere il valore della casella di selezione all’invio di un form

Aggiungi un <form> intorno alla tua casella select con un <button type="submit"> al suo interno. Invocherà il tuo gestore di eventi <form onSubmit>. Per impostazione predefinita, il browser invierà i dati del form all’URL corrente e ricaricherà la pagina. Puoi sovrascrivere questo comportamento chiamando e.preventDefault(). Leggi i dati del form con new FormData(e.target).

export default function EditPost() {
  function handleSubmit(e) {
    // Impedisci al browser di ricaricare la pagina
    e.preventDefault();
    // Leggi i dati del form
    const form = e.target;
    const formData = new FormData(form);
    // Puoi passare formData come body di fetch direttamente:
    fetch('/some-api', { method: form.method, body: formData });
    // Puoi generare un URL da esso, come fa il browser di default:
    console.log(new URLSearchParams(formData).toString());
    // Puoi lavorarci come con un oggetto semplice.
    const formJson = Object.fromEntries(formData.entries());
    console.log(formJson); // (!) Questo non include i valori di select multipli
    // Oppure puoi ottenere un array di coppie nome-valore.
    console.log([...formData.entries()]);
  }

  return (
    <form method="post" onSubmit={handleSubmit}>
      <label>
        Pick your favorite fruit:
        <select name="selectedFruit" defaultValue="orange">
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="orange">Orange</option>
        </select>
      </label>
      <label>
        Pick all your favorite vegetables:
        <select
          name="selectedVegetables"
          multiple={true}
          defaultValue={['corn', 'tomato']}
        >
          <option value="cucumber">Cucumber</option>
          <option value="corn">Corn</option>
          <option value="tomato">Tomato</option>
        </select>
      </label>
      <hr />
      <button type="reset">Reset</button>
      <button type="submit">Submit</button>
    </form>
  );
}

Nota bene

Assegna un name al tuo <select>, ad esempio <select name="selectedFruit" />. Il name che hai specificato verrà usato come chiave nei dati del form, ad esempio { selectedFruit: "orange" }.

Se usi <select multiple={true}>, il FormData che leggerai dal form includerà ogni valore selezionato come coppia nome-valore separata. Osserva attentamente i log della console nell’esempio sopra.

Insidia

Per impostazione predefinita, qualsiasi <button> dentro un <form> lo invierà. Questo può sorprendere! Se hai un tuo componente React Button personalizzato, considera di restituire <button type="button"> invece di <button>. Poi, per essere esplicito, usa <button type="submit"> per i pulsanti che devono inviare il form.

Controllare una casella di selezione con una variabile di state

Una casella select come <select /> è non controllata. Anche se passi un valore inizialmente selezionato come <select defaultValue="orange" />, il tuo JSX specifica solo il valore iniziale, non il valore attuale.

Per renderizzare una casella select controllata, passa la prop value. React forzerà la casella select ad avere sempre il value che hai passato. Di solito, controllerai una casella select dichiarando una variabile di state:

function FruitPicker() {
  const [selectedFruit, setSelectedFruit] = useState('orange'); // Dichiara una variabile di state...
  // ...
  return (
    <select
      value={selectedFruit} // ...forza il valore del select a corrispondere alla variabile di state...
      onChange={e => setSelectedFruit(e.target.value)} // ... e aggiorna la variabile di state a ogni modifica!
    >
      <option value="apple">Apple</option>
      <option value="banana">Banana</option>
      <option value="orange">Orange</option>
    </select>
  );
}

Questo è utile se vuoi ri-renderizzare una parte dell’UI in risposta a ogni selezione.

import { useState } from 'react';

export default function FruitPicker() {
  const [selectedFruit, setSelectedFruit] = useState('orange');
  const [selectedVegs, setSelectedVegs] = useState(['corn', 'tomato']);
  return (
    <>
      <label>
        Pick a fruit:
        <select
          value={selectedFruit}
          onChange={e => setSelectedFruit(e.target.value)}
        >
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="orange">Orange</option>
        </select>
      </label>
      <hr />
      <label>
        Pick all your favorite vegetables:
        <select
          multiple={true}
          value={selectedVegs}
          onChange={e => {
            const options = [...e.target.selectedOptions];
            const values = options.map(option => option.value);
            setSelectedVegs(values);
          }}
        >
          <option value="cucumber">Cucumber</option>
          <option value="corn">Corn</option>
          <option value="tomato">Tomato</option>
        </select>
      </label>
      <hr />
      <p>Your favorite fruit: {selectedFruit}</p>
      <p>Your favorite vegetables: {selectedVegs.join(', ')}</p>
    </>
  );
}

Insidia

Se passi value senza onChange, sarà impossibile selezionare un’opzione. Quando controlli una casella select passandogli un value, la forzi ad avere sempre il valore che hai passato. Quindi se passi una variabile di state come value ma dimentichi di aggiornare quella variabile di state in modo sincrono durante il gestore di eventi onChange, React ripristinerà la casella select dopo ogni battitura al value che hai specificato.

A differenza dell’HTML, passare un attributo selected a un singolo <option> non è supportato.

Previous<progress>
Next<textarea>