Aller au contenu principal
Version: 26.0.10.0

forms.checkbox()

Génère une case à cocher (checkbox) avec label et texte d'aide.

Signature​

{{ forms.checkbox(label, name, checked, options) }}

Paramètres​

label​

  • Type : string
  • Description : Le label affiché à côté de la checkbox
  • Exemple : "J'accepte les CGU"

name (Requis)​

  • Type : string
  • Description : Le nom du champ (attribut name)
  • Exemple : 'cgu_accepted'

checked​

  • Type : bool
  • Description : Si la checkbox est cochée par défaut
  • Défaut : false
  • Exemple : true

options​

  • Type : array
  • Description : Options de personnalisation

Options disponibles​

OptionTypeDescriptionDéfaut
classstringClasse CSS du conteneur""
input_classstringClasse CSS de la checkbox""
requiredboolRend la checkbox obligatoirefalse
help_textstringTexte d'aide sous la checkbox""

Exemples​

Checkbox simple​

{{ forms.checkbox("J'accepte les CGU", 'cgu', false, {}) }}

Rendu HTML :

<div class="input-group inline">
    <input
        type="checkbox"
        id="cgu"
        name="cgu"
        value="1"
        class="form-check-input"
    />
    <div class="labels">
        <label class="form-check-label" for="cgu">J'accepte les CGU</label>
    </div>
</div>

Checkbox cochée par défaut​

{{ forms.checkbox('Recevoir la newsletter', 'newsletter', true, {}) }}

Checkbox requise​

{{ forms.checkbox("J'accepte les conditions d'utilisation", 'terms', false, {
    required: true
}) }}

Checkbox avec texte d'aide​

{{ forms.checkbox('Me tenir informé des nouveautés', 'updates', false, {
    help_text: 'Vous recevrez un email mensuel maximum'
}) }}

Checkbox avec classes personnalisées​

{{ forms.checkbox('Option premium', 'premium', false, {
    class: 'custom-checkbox-container',
    input_class: 'custom-checkbox'
}) }}

Cas d'usage​

Formulaire d'inscription​

{% import "@elementum/macros/forms.html.twig" as forms %}

<form method="post">
    {{ forms.csrf_nonce() }}

    {{ forms.input('Email', 'email', '', 'email', { required: true }) }}
    {{ forms.input('Mot de passe', 'password', '', 'password', { required: true }) }}

    {{ forms.checkbox("J'accepte les CGU", 'cgu', false, {
        required: true,
        help_text: 'Veuillez lire nos conditions générales d utilisation'
    }) }}

    {{ forms.checkbox('Recevoir notre newsletter', 'newsletter', false, {}) }}

    {{ forms.submit("S'inscrire") }}
</form>

Filtres de recherche​

{% import "@elementum/macros/forms.html.twig" as forms %}

<form method="get">
    {{ forms.checkbox('Uniquement en promotion', 'on_sale', request.on_sale == '1', {}) }}
    {{ forms.checkbox('En stock uniquement', 'in_stock', request.in_stock == '1', {}) }}

    <button type="submit">Filtrer</button>
</form>

Formulaire de profil utilisateur​

{% import "@elementum/macros/forms.html.twig" as forms %}

<form method="post">
    {{ forms.csrf_nonce() }}

    <h3>Préférences de notification</h3>

    {{ forms.checkbox('Nouveaux commentaires', 'notify_comments', user.notify_comments, {}) }}
    {{ forms.checkbox('Nouveaux messages', 'notify_messages', user.notify_messages, {}) }}
    {{ forms.checkbox('Offres spéciales', 'notify_offers', user.notify_offers, {
        help_text: 'Recevez nos meilleures offres par email'
    }) }}

    {{ forms.submit('Enregistrer') }}
</form>

Structure HTML​

La macro génère la structure suivante :

<div class="input-group inline [class]">
    <input
        type="checkbox"
        id="[name]"
        name="[name]"
        value="1"
        class="form-check-input [input_class]"
        [checked]
        [required]
    />
    <div class="labels">
        <label class="form-check-label" for="[name]">[label]</label>
        [si help_text:
        <small class="form-text text-muted d-block">[help_text]</small>]
    </div>
</div>

Bonnes pratiques​

  1. Toujours inclure un label : Pour l'accessibilité, ne jamais omettre le label
  2. Utiliser required avec parcimonie : Une checkbox obligatoire peut frustrer les utilisateurs
  3. Ajouter un help_text pour les options importantes : Clarifie les conséquences du choix
  4. Gérer l'état coché dans le controller : Conserver l'état lors de la soumission d'un formulaire

Voir aussi​