Regione Toscana Design System — Servizi Design System Core

Input element: Has Description 

<div class="rtds-input rtds-input-field rtds-input-checkbox">

    <div class="rtds-flex rtds-gap-2 rtds-items-center">
        <input id="checkboxId" name="checkboxId" class="   " type="checkbox" aria-describedBy="idInputDescription">
        <label class="rtds-input-checkbox__label" for="checkboxId">
            label checkbox
        </label>
    </div>

    <span class="rtds-input-field__hint">

        <span class="rtds-input-field__description" id="idInputDescription">
            descrizione
        </span>

    </span>

</div>
 
<div class="rtds-input rtds-input-field rtds-input-checkbox{% block size %}{% endblock size %}{% if classes %} {{ classes }}{% endif %}{% if hasError %} has-error{% endif %}">
  {% if errorId is not defined %} 
   {% set errorId = id ~ 'Error' %} {% endif %}
    {%- if iconPlaceholder %}
      {% render '@icon', {id: iconPlaceholder, classes: 'rtds-absolute rtds-left-4 rtds-content-placeholder', size: 'rtds-w-6 rtds-h-6'}, true %}
    {% endif -%}
      <div class="rtds-flex rtds-gap-2 rtds-items-center">
        <input
          id="{{ id }}"
          name="{{ id }}"
          {% if shortLabel %} data-label="{{ shortLabel }}"{% endif %}
          class="{{ padding }} {{ radius }} {{ border }} {% if inputClasses %} {{ inputClasses }}{% endif %}" type="checkbox"
          {% if fieldRequired %} aria-required="true"{% endif %}
          {% if ariaDescribedBy or hasErrorControl or fieldRequired %} aria-describedBy="
            {%- if hasErrorControl or fieldRequired -%}
            {{- errorId -}}
            {%- if ariaDescribedBy %} {{ ariaDescribedBy -}}{%- endif -%}
            {% elseif ariaDescribedBy -%}
            {{- ariaDescribedBy -}}
            {% endif %}"
          {% endif %}
          {% if ariaInvalid %} aria-invalid="true"{% endif %}
          {% if checked %} checked{% endif %}
          {% if disabled %} disabled{% endif %}
          >
          <label class="rtds-input-checkbox__label{% if labelClasses %} {{ labelClasses }}{% endif %}" for="{{ id }}">
            {{ label | safe }}
            {% if fieldRequired %}<abbr class="rtds-font-bold rtds-no-underline" title="obbligatorio">*</abbr>{% endif %}
              {%- if iconAlert %}
              {% render '@icon', {id: 'outline--exclamation-circle', classes: 'rtds-absolute rtds-right-4 rtds-content-placeholder rtds-content-error', size: 'rtds-w-6 rtds-h-6'}, true %}
            {% endif -%}
          </label>
        </div>
      {% if inFieldset == false %}
        {% if fieldRequired or ariaDescribedBy or hasErrorControl %}
        <span class="rtds-input-field__hint">
          {% if fieldRequired or hasErrorControl %}
            <span class="rtds-input-field__error" id="{{ id }}Error" aria-live="assertive">
                {{ errorDescription }}
            </span>
            {% endif %}
            {% if inputDescription %}
            <span class="rtds-input-field__description" id="{{ ariaDescribedBy }}">
                {{ inputDescription }}
            </span>
            {% endif %}
        </span>
      {% endif %}
    {% endif %}
</div>
 
{
  "label": "label checkbox",
  "id": "checkboxId",
  "inFieldset": false,
  "ariaDescribedBy": "idInputDescription",
  "inputDescription": "descrizione"
}
  • Content: 
    /**
 * INPUT
 * 
 *
*/
.rtds-input-checkbox input[type="checkbox"] {
    border-radius: 0.25rem;
        border-color: var(--color-border-input);
    width: var(--spacing-5);
    height: var(--spacing-5);
}
.rtds-input-checkbox__label {
    cursor: pointer;
    font-size: var(--fontsize-text-base);
    font-weight: 500;
}
/* SIZES */
.rtds-input--sm input[type="checkbox"] {
    width: var(--spacing-4);
    height: var(--spacing-4);
}
:where(.rtds-input--sm) .rtds-input-checkbox__label {
    font-size: var(--fontsize-text-sm);
}
.rtds-input--lg input[type="checkbox"] {
    width: var(--spacing-6);
    height: var(--spacing-6);
}
.has-error input[type="checkbox"] {
    border-width: 2px;
    border-color: var(--color-error-dark);
}
/* DISABLED STATE */
:where(.rtds-input-checkbox) input[type="checkbox"]:disabled {
        border-color: var(--color-border-gray-03);
        cursor: not-allowed;
    }
:where(.rtds-input-checkbox) input[type="checkbox"]:disabled ~ .rtds-input-checkbox__label {
        color: var(--color-content-disabled);
        cursor: not-allowed;
    }
  • URL: /components/raw/input-checkbox/input-checkbox.built.css
  • Filesystem Path: components/03-molecules/forms/input-checkbox/input-checkbox.built.css
  • Size: 1.1 KB
  • Content: 
    /**
 * INPUT
 * 
 *
*/
@layer components {
    .rtds-input-checkbox input[type="checkbox"] {
        @apply rtds-w-5 rtds-h-5 rtds-border-input rtds-rounded;
    }

    .rtds-input-checkbox__label {
        @apply rtds-text-base rtds-font-medium rtds-cursor-pointer;
    }

    /* SIZES */

    .rtds-input--sm input[type="checkbox"] {
        @apply rtds-w-4 rtds-h-4;
    }

    :where(.rtds-input--sm) .rtds-input-checkbox__label {
        @apply rtds-text-sm;
    }

    .rtds-input--lg input[type="checkbox"] {
        @apply rtds-w-6 rtds-h-6;
    }


    .has-error input[type="checkbox"]{
        @apply rtds-border-error-dark rtds-border-2;
    }

    /* DISABLED STATE */
    :where(.rtds-input-checkbox) input[type="checkbox"]:disabled {
        border-color: var(--color-border-gray-03);
        cursor: not-allowed;
    }

    :where(.rtds-input-checkbox) input[type="checkbox"]:disabled ~ .rtds-input-checkbox__label {
        color: var(--color-content-disabled);
        cursor: not-allowed;
    }
}
  • URL: /components/raw/input-checkbox/input-checkbox.css
  • Filesystem Path: components/03-molecules/forms/input-checkbox/input-checkbox.css
  • Size: 1 KB
  • Handle: @input-checkbox--has-description
  • Preview:
  • Filesystem Path: components/03-molecules/forms/input-checkbox/input-checkbox.njk
  • References (1): @icon

Input Checkbox

Componente per la gestione di input di tipo checkbox con supporto per accessibilità, validazione e gestione degli errori.

Comportamento

Il componente renderizza un <input type="checkbox"> con la relativa <label> associata. Supporta stati di errore, descrizione e obbligatorietà. Quando usato all’interno di un <fieldset> (inFieldset: true), i messaggi di errore e descrizione sono gestiti dal componente parent checkbox-fieldset.

Varianti

Varianti di Stato

  • default: Configurazione base del checkbox
  • is-required: Checkbox obbligatorio
  • has-error-markup: Checkbox con markup per la gestione degli errori
  • has-description: Checkbox con descrizione aggiuntiva
  • has-error: Checkbox con stato di errore
  • has-error-and-description: Checkbox con stato di errore e descrizione
  • disabled: Checkbox non disponibile — escluso dal tab order, non inviato nel form; label e controllo appaiono muted

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — Questa sezione riguarda esclusivamente i parametri del context .config.yml usati durante lo sviluppo nella libreria. Non descrive attributi HTML o proprietà da usare nei temi, CMS o ambienti di implementazione: per quello, fare riferimento alla sezione Esempi di utilizzo.

Parametri Base

  • label (stringa, obbligatorio): Etichetta del checkbox
  • id (stringa, obbligatorio): Identificatore univoco dell’input
  • shortLabel (stringa, opzionale): Versione abbreviata dell’etichetta per l’attributo data-label (necessario per la gestione degli errori via JavaScript)
  • labelClasses (stringa, opzionale): Classi CSS aggiuntive per l’etichetta
  • padding (stringa, opzionale): Padding dell’input
  • border (stringa, opzionale): Stile del bordo dell’input
  • radius (stringa, opzionale): Raggio del bordo dell’input
  • classes (stringa, opzionale): Classi CSS aggiuntive per l’input

Parametri di Accessibilità

  • fieldRequired (booleano, opzionale): Se true, stampa aria-required="true" invece dell’attributo required e aggiunge il wrapper del messaggio di errore
  • ariaDescribedBy (stringa, opzionale): ID dell’elemento che descrive il campo
  • hasErrorControl (booleano, opzionale): Se true, attiva la validazione dell’input
  • ariaInvalid (booleano, opzionale): Se true, aggiunge aria-invalid="true" all’input
  • alertIcon (stringa, opzionale): ID per l’icona di alert posizionata a destra
  • inFieldset (booleano, opzionale): Se true, indica che l’input è contenuto in un fieldset
  • disabled (booleano, opzionale): Se true, aggiunge l’attributo disabled — il checkbox è non interattivo, escluso dal tab order e non inviato nel form. La label appare muted tramite color: --color-content-disabled

Nota: <input type="checkbox"> non supporta readonly. Per un checkbox “visibile ma non modificabile”, usare disabled con il valore pre-selezionato e un <input type="hidden"> separato per inviare il valore nel form.

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

  • 1.3.1 Informazioni e correlazioni — la <label> è sempre associata all’<input> tramite for / id
  • 3.3.1 Identificazione degli errori — gli errori sono comunicati tramite aria-invalid e annunciati con aria-live="assertive"
  • 3.3.2 Etichette o istruzioni — ogni checkbox ha una <label> visibile associata
  • 4.1.2 Nome, ruolo, valore — aria-required, aria-describedby e aria-invalid comunicano lo stato del campo

Struttura e semantica

  • Il componente è renderizzato come <div> contenente un <input type="checkbox"> e la relativa <label> associata tramite for / id
  • L’indicatore di campo obbligatorio è un <abbr title="obbligatorio">*</abbr> nella label
  • Quando usato all’interno di un <fieldset> (inFieldset: true), i messaggi di errore e descrizione sono gestiti dal componente parent checkbox-fieldset

Attributi ARIA

Attributo Valori Condizione
aria-required "true" quando fieldRequired è true
aria-describedby ID del messaggio di errore e/o descrizione quando presenti errori o descrizione
aria-invalid "true" quando ariaInvalid è true
aria-live "assertive" sullo span del messaggio di errore (solo se non in fieldset)

Screen reader

  • Lo screen reader annuncia il checkbox con il testo della label, il ruolo (casella di controllo), lo stato selezionato/deselezionato e l’eventuale stato di errore
  • I messaggi di errore vengono annunciati immediatamente grazie ad aria-live="assertive"
  • L’indicatore di obbligatorietà (*) è leggibile tramite l’attributo title="obbligatorio" sull’<abbr>

Esempi di utilizzo

<!-- Esempio base -->
<div class="rtds-input rtds-input-checkbox">
  <input type="checkbox" id="my-checkbox" name="my-checkbox">
  <label for="my-checkbox">Accetto i termini e le condizioni</label>
</div>

<!-- Esempio obbligatorio con errore -->
<div class="rtds-input rtds-input-checkbox">
  <input type="checkbox" id="required-checkbox" name="required-checkbox"
         aria-required="true" aria-invalid="true" aria-describedby="checkbox-error">
  <label for="required-checkbox">
    Accetto i termini <abbr title="obbligatorio">*</abbr>
  </label>
  <span class="rtds-input-field__hint">
    <span id="checkbox-error" aria-live="assertive" class="rtds-input-field__error">
      È necessario accettare i termini per procedere
    </span>
  </span>
</div>

Note

  • Il componente utilizza il sistema di classi RTDS per lo styling
  • Supporta l’integrazione con icone attraverso il componente icon
  • La gestione degli errori può essere personalizzata via JavaScript utilizzando l’attributo data-label