Dropdown
Attiva o disattiva overlay contestuali per visualizzare liste di link ed altro ancora con questi menu a tendina.
Il plugin JavaScript per costruire dropdown è basato su una libreria di terze parti, Popper.js, che si occupa del posizionamento dinamico del dropdown stesso in congiunzione con la sua posizione all’interno del viewport.
Per il corretto funzionamento dei dropdown è necessario assicurarsi che sia incluso il file bootstrap-italia.bundle.min.js che contiene già ogni dipendenza, oppure che il file popper.min.js sia incluso prima del file bootstrap-italia.min.js. Maggiori informazioni si possono trovare alla pagina introduttiva sull’utilizzo del JavaScript di Bootstrap Italia.
Per l’attivazione di un dropdown è sufficiente racchiudere il link per l’apertura e il menu a discesa all’interno di un elemento con classe .dropdown, o un altro elemento che dichiari la position: relative;. I dropdown possono essere attivati da elementi <a> o <button> per soddisfare al meglio le tue esigenze.
Accessibilità
Lo standard WAI ARIA definisce un widget con proprietà role="menu", specifica per i menu applicativi con link o azioni. Questi menu possono contenere solo voci di menu, voci di menu di caselle di controllo, voci di menu dei pulsanti di opzione, gruppi di pulsanti di opzione e sottomenu.
I dropdown del framework Bootstrap sono progettati per essere invece generici e applicabili a una varietà di situazioni e strutture di markup. Per questo motivo, Bootstrap non si aspetta (né aggiunge automaticamente) alcuno degli attributi ARIA e di ruolo richiesti. Gli autori dovranno integrare nel proprio markup gli eventuali attributi specifici e, nel caso di sviluppo di soluzioni che non ricadano nello standard ARIA, porre particolare attenzione a verifiche di accessibilità e test con utenti.
Tuttavia, Bootstrap comprende di base il supporto per la maggior parte delle interazioni standard del menu della tastiera, come la possibilità di spostarsi tra i singoli elementi .list-item usando i tasti freccia, e chiude il menu con il tasto ESC.
Si ricorda che link di navigazione semanticamente sono tag <a>, mentre link che attivano azioni in pagina sono tag <button>, seppur questi ultimi è possibile implementarli in casi molto particolari come tag <a> con proprietà role="button".
Dropdown button
Ogni singolo .btn può essere trasformato in un pulsante per l’apertura di dropdown con del semplice markdown HTML.
Il design di default dei dropdown richiede l’applicazione della classe .btn-dropdown. I link o le voci all’interno del dropdown devono essere contenute in un elemento .link-list.
Dropdown button varianti
Ovviamente sono disponibili tutte le varianti già disponibili per i pulsanti. Di seguito, un esempio di utilizzo con classi .btn-primary, .btn-secondary e .btn-danger:
Dropdown link
Lo stesso vale per gli elementi <a>:
Dropup
Per aprire le voci di menu verso l’alto aggiungere la classe .dropup all’elemento padre.
Dropend
Per aprire le voci di menu verso destra aggiungere la classe .dropend all’elemento padre.
Dropstart
Per aprire le voci di menu verso sinistra aggiungere la classe .dropstart all’elemento padre.
Dropdown menu
Le voci del menu che viene aperto al click sul pulsante possono essere personalizzate, così come il menu stesso.
Menu voci attive
Aggiungere la classe .active ai link del dropdown che si vogliono mostrare come attivi. Per questioni di accessibilità è consigliabile aggiungere <span class="visually-hidden"> attivo</span> in coda al testo degli elementi attivi.
Menu voci disabilitate
Aggiungere la classe .disabled ai link del dropdown che si vogliono mostrare come disabilitati. Includere anche la proprietà aria-disabled="true" per comunicare lo stato disabilitato agli utenti dotati di screen reader.
Menu con intestazioni e separatori
All’interno del menu dropdown possono essere inseriti header e separatori.
Menu con voci grandi
Per aumentare la dimensione dei link contenuti nel dropdown è sufficiente aggiungere agli stessi la classe .large.
Menu a tutta larghezza
Per ottenere un dropdown menu largo quanto l’elemento che contiene il dropdown button è sufficiente aggiungere la classe.full-width al menu stesso. I link e testi contenuti al suo interno saranno disposti in orizzontale.
Menu con icona a destra
Ai link contenuti nel menu può essere aggiunta un’icona illustrativa allineata a destra utilizzando le classi .right-icon sul link <a> e .right sul tag contenitore dell’icona.
Menu con icona a sinistra
Ai link contenuti nel menu può essere aggiunta un’icona illustrativa allineata a sinistra utilizzando le classi .left-icon sul link <a> e .left sul tag contenitore dell’icona.
Menu scuro
Aggiungendo la classe.dark al dropdown menu si ottiene una versione con un colore primario scuro. Link ed elementi interni vengono declinati di conseguenza.
Attivazione tramite codice
Nel caso in cui si desidera che il componente sia inizializzato in maniera automatica
utilizzare l’attributo data-bs-toggle specifico per la sua inizializzazione.
Nel caso in cui si desidera importare e inizializzare autonomamente il componente
l’attributo data-bs-toggle specifico non deve essere incluso così da evitare
inizializzazioni automatiche che possono portare a comportamenti inaspettati.
Per maggiori informazioni consulta la sezione JavaScript di Bootstrap Italia.
1
2
3
4
import { Dropdown } from 'bootstrap-italia';
const dropdownEl = document.getElementById('myDropdown');
const dropdown = new Dropdown(dropdownEl, options)
Opzioni
Le opzioni possono essere passate tramite gli attributi data o tramite JavaScript. Per quanto riguarda gli attributi data, aggiungi il nome dell’opzione a data-bs, come in data-bs-parent="".
| Nome | Tipo | Predefinito | Descrizione |
|---|---|---|---|
| autoClose | true | 'inside' | 'outside' | true | Configura il comportamento di chiusura automatica del menu a discesa:
true - il menu a discesa verrà chiuso cliccando all'esterno o all'interno del menu a discesa. false - il menu a discesa verrà chiuso cliccando sul pulsante di attivazione/disattivazione e richiamando manualmente il metodo hide o toggle. (Inoltre, non verrà chiuso premendo il tasto esc) 'inside' - il menu a discesa verrà chiuso (solo) cliccando all'interno del menu a discesa. 'outside' - il menu a discesa verrà chiuso (solo) cliccando all'esterno del menu a discesa. Nota: il menu a discesa può sempre essere chiuso con il tasto ESC. |
| boundary | string | element | "clippingParents" | Limite di vincolo di overflow del menu a discesa (si applica solo al modificatore preventOverflow di Popper). Di default è clippingParents e può accettare un riferimento HTMLElement (solo tramite JavaScript). Per maggiori informazioni, fare riferimento alla documentazione detectOverflow di Popper. |
| display | string | "dynamic" | Di default, viene utilizzato Popper per il posizionamento dinamico. Questo comportament è disattivabile con il valore "static". |
| offset | array|string|function | [0, 2] | Offset del menu a discesa rispetto al suo target. Puoi passare una stringa negli attributi dati con valori separati da virgole. Quando una funzione viene utilizzata per determinare l'offset, viene chiamata con un oggetto contenente il posizionamento del popper, il riferimento e i rettangoli del popper come primo argomento. Il nodo DOM dell'elemento di attivazione viene passato come secondo argomento. La funzione deve restituire un array con due numeri: skidding, distance. Per maggiori informazioni, fai riferimento alla documentazione offset di Popper. |
| popperConfig | null|object|function | null | Configurazione aggiuntiva per l'oggetto Popper.js presente nel componente dropdown. Per maggiori informazioni si rimanda alla documentazione della configurazione Popper |
| reference | string|element|object | "toggle" | Elemento di riferimento del menu a discesa. Accetta i valori di 'toggle', 'parent', un riferimento HTMLElement o un oggetto che fornisce getBoundingClientRect. Per maggiori informazioni si rimanda alla documentazione di Popper. |
Metodi
| Metodo | Descrizione |
|---|---|
| getInstance | Metodo statico che consente di ottenere l'istanza di avviso associata a un elemento DOM, è possibile utilizzarlo in questo modo: Dropdown.getInstance(domElement). |
| getOrCreateInstance | Metodo statico che restituisce un'istanza di avviso associata a un elemento DOM o ne crea una nuova nel caso in cui non fosse stata inizializzata. Puoi utilizzarla in questo modo: Dropdown.getOrCreateInstance(element). |
| dispose | Rimuove la funzionalità Dropdown. |
| show | Mostra la tendina del dropdown. |
| hide | Nasconde la tendina del dropdown. |
| toggle | Mostra/nasconde la tendina del dropdown. |
Eventi
| Evento | Descrizione |
|---|---|
hide.bs.dropdown |
Viene attivato immediatamente quando viene chiamato il metodo di istanza hide. |
hidden.bs.dropdown |
Viene attivato quando il menu a discesa non è più nascosto all'utente e le transizioni CSS sono state completate. |
show.bs.dropdown |
Viene attivato immediatamente quando viene chiamato il metodo di istanza show. chiamato.
|
shown.bs.dropdown |
Attivato quando il menu a discesa è stato reso visibile all'utente e le transizioni CSS sono state completate. |
Properties
| Variabile CSS | Descrizione (Inglese) | Predefinito |
|---|---|---|
--bsi-dropdown-animation-speed |
Controls the speed of the dropdown open animation, using transition tokens. | var(--bsi-transition-instant) |
--bsi-dropdown-background |
Controls the default background, using color tokens. | var(--bsi-color-background-inverse) |
--bsi-dropdown-border-color |
Controls the default border color. | transparent |
--bsi-dropdown-border-radius |
Controls the border radius, using radius tokens. | var(--bsi-radius-smooth) |
--bsi-dropdown-border-width |
Controls the border width. | 0 |
--bsi-dropdown-box-shadow |
Controls the box shadow, using elevation tokens. | var(--bsi-elevation-medium) |
--bsi-dropdown-color |
Controls the default text color, using color tokens. | var(--bsi-color-text-base) |
--bsi-dropdown-divider-bg |
Controls the divider background color, using color tokens. | var(--bsi-color-border-subtle) |
--bsi-dropdown-divider-margin-y |
Controls the divider margin top and bottom, using spacing tokens. | var(--bsi-spacing-xxs) |
--bsi-dropdown-font-size |
Controls the font size of dropdown items, using font tokens. | var(--bsi-label-font-size) |
--bsi-dropdown-header-color |
Controls the dropdown header text color, using color tokens. | var(--bsi-color-text-secondary) |
--bsi-dropdown-header-font-size |
Controls the dropdown header font size, using font tokens. | var(--bsi-label-font-size) |
--bsi-dropdown-header-padding-x |
Controls the dropdown header padding left and right, using spacing tokens. | var(--bsi-spacing-s) |
--bsi-dropdown-header-padding-y |
Controls the dropdown header padding top and bottom, using spacing tokens. | var(--bsi-spacing-xxs) |
--bsi-dropdown-inner-border-radius |
Controls the inner border radius for first and last items, using radius tokens. | var(--bsi-radius-smooth) |
--bsi-dropdown-item-padding-x |
Controls the dropdown item padding left and right, using spacing tokens. | var(--bsi-spacing-s) |
--bsi-dropdown-item-padding-y |
Controls the dropdown item padding top and bottom, using spacing tokens. | var(--bsi-spacing-xs) |
--bsi-dropdown-link-active-color |
Controls the active link color, using color tokens. | var(--bsi-color-text-primary-active) |
--bsi-dropdown-link-color |
Controls the link color in dropdown items, using color tokens. | var(--bsi-color-text-primary) |
--bsi-dropdown-link-hover-color |
Controls the link hover color in dropdown items, using color tokens. | var(--bsi-color-text-primary-hover) |
--bsi-dropdown-min-width |
Controls the minimum width of the dropdown menu. | 10rem |
--bsi-dropdown-notch-base-size |
Controls the size of the notch element. | 1.125rem |
--bsi-dropdown-notch-position-x |
Controls the x position of the notch element. | 20px |
--bsi-dropdown-notch-position-y |
Controls the y position of the notch element. | -8px |
--bsi-dropdown-padding-x |
Controls the dropdown menu padding left and right. | 0 |
--bsi-dropdown-padding-y |
Controls the dropdown menu padding top and bottom, using spacing tokens. | var(--bsi-spacing-xxs) |
--bsi-dropdown-spacer |
Controls the space between dropdown toggle and menu. | 0.125rem |
--bsi-dropdown-vertical-shift |
Controls the vertical shift for dropdown open animation. | 10px |
--bsi-dropdown-zindex |
Controls the z-index of the dropdown menu. | 8 |
Breaking change
- Per quanto riguarda le icone le classi che ne controllano il colore potrebbero aver cambiato nome, ad esempio
.icon-whitediventa.icon-inverse. - Aggiunta classe
.dropdown-itemalla voce attiva nell’esempio di menu voci attive ed a tutti agli elementi dei menu dropdown laddove mancava. - Corretto markup dell’intestazione nel Menu con intestazioni e separatori,
<div>diventa<h4>. Sarà da far attenzione alla corretta gerarchia in pagina di questa intestazione scegliendone il livello a seconda del contesto.