ButtonGroup
===========

.. granite:servercomponent:: /libs/granite/ui/components/coral/foundation/form/buttongroup
   :supertype: /libs/granite/ui/components/coral/foundation/form/field

   A container to group a set of buttons.
   The user is able to select one or more buttons. The selected values are then submitted during form submission.

   It extends :granite:servercomponent:`Field </libs/granite/ui/components/coral/foundation/form/field>` component.

   It has the following content structure:

   .. gnd:gnd::

      [granite:FormButtonGroup] > granite:FormField, granite:container

      /**
       * The name that identifies the field when submitting the form.
       */
      - name (String)

      /**
       * The selection mode.
       *
       * none
       *    Nothing can be selected.
       * single
       *    Only a single item can be selected.
       * multiple
       *    Multiple items can be selected.
       */
      - selectionMode = 'none' < 'none', 'single', 'multiple'

      /**
       * ``true`` to generate the `SlingPostServlet @Delete <http://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html#delete>`_ hidden input based on the name.
       */
      - deleteHint (Boolean) = true

      /**
       * Indicates if the field is mandatory to be filled.
       */
      - required (Boolean)

      /**
       * The name of the validator to be applied. E.g. ``foundation.jcr.name``.
       * See :doc:`validation </jcr_root/libs/granite/ui/components/coral/foundation/clientlibs/foundation/js/validation/index>` in Granite UI.
       */
      - validation (String) multiple

      /**
       * If ``false``, the checked status is based on matching the form values by ``name`` and ``value`` properties.
       * Otherwise, the form values are not matched, and the checked status of each item is based on its ``checked`` property.
       */
      - ignoreData (Boolean)

   Each item has the following content structure:

   .. gnd:gnd::

      [granite:FormButtonGroupItem] > granite:commonAttrs

      /**
       * The value of the item.
       */
      - value (String)

      /**
       * Indicates if the item is in disabled state.
       */
      - disabled (Boolean)

      /**
       * ``true`` to pre-check this item, ``false`` otherwise.
       */
      - checked (Boolean)

      /**
       * The text of the item.
       */
      - text (String) i18n

      /**
       * Visually hide the text.
       * It is RECOMMENDED that every item has a text for a11y purpose.
       * Use this property to hide it visually, while still making it available for a11y.
       */
      - hideText (Boolean)

      /**
       * The icon name. e.g. "search".
       */
      - icon (String)

      /**
       * The size of the icon.
       */
      - iconSize (String) = 'S' < 'XS', 'S', 'M', 'L'