vaadin/vaadin-checkbox

The Web Component for customized checkboxes. Part of the Vaadin components.

<vaadin-checkbox>

⚠️ Starting from Vaadin 20, the source code and issues for this component are migrated to the vaadin/web-components monorepository. This repository contains the source code and releases of <vaadin-checkbox> for the Vaadin versions 10 to 19.

<vaadin-checkbox> is a Web Component providing an accessible and customizable checkbox, part of the Vaadin components.

Live Demo ↗ | API documentation ↗

<vaadin-checkbox checked>Checked</vaadin-checkbox>
<vaadin-checkbox>Unchecked</vaadin-checkbox>
<vaadin-checkbox indeterminate>Indeterminate</vaadin-checkbox>

Installation

The Vaadin components are distributed as Bower and npm packages. Please note that the version range is the same, as the API has not changed. You should not mix Bower and npm versions in the same application, though.

Unlike the official Polymer Elements, the converted Polymer 3 compatible Vaadin components are only published on npm, not pushed to GitHub repositories.

Polymer 2 and HTML Imports Compatible Version

Install vaadin-checkbox:

bower i vaadin/vaadin-checkbox --save

Once installed, import it in your application:

<link rel="import" href="bower_components/vaadin-checkbox/vaadin-checkbox.html">

Polymer 3 and ES Modules Compatible Version

Install vaadin-checkbox:

npm i @vaadin/vaadin-checkbox --save

Once installed, import it in your application:

import '@vaadin/vaadin-checkbox/vaadin-checkbox.js';

Getting Started

Vaadin components use the Lumo theme by default.

To use the Material theme, import the correspondent file from the theme/material folder.

The file structure for Vaadin components

• The component with the Lumo theme:

  theme/lumo/vaadin-checkbox.html

• The component with the Material theme:

  theme/material/vaadin-checkbox.html

• Alias for theme/lumo/vaadin-checkbox.html:

  vaadin-checkbox.html

Running demos and tests in a browser

1. Fork the vaadin-checkbox repository and clone it locally.

2. Make sure you have npm and Bower installed.

3. When in the vaadin-checkbox directory, run npm install and then bower install to install dependencies.

4. Run npm start, browser will automatically open the component API documentation.

5. You can also open demo or in-browser tests by adding demo or test to the URL, for example:

• http://127.0.0.1:3000/components/vaadin-checkbox/demo
• http://127.0.0.1:3000/components/vaadin-checkbox/test

Running tests from the command line

1. When in the vaadin-checkbox directory, run polymer test

Following the coding style

We are using ESLint for linting JavaScript code. You can check if your code is following our standards by running npm run lint, which will automatically lint all .js files as well as JavaScript snippets inside .html files.

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.

Contributing

To contribute to the component, please read the guideline first.

License

Apache License 2.0

Vaadin collects development time usage statistics to improve this product. For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

vaadin-checkbox's Issues

Revert #43

Reverting checkbox behavior to what it was originally (aligned with native checkbox)

#42 (comment)

Indeterminate mode demo broken on IE

The demo source isn't transpiled so it should be written in ES5 like the other demos

Broken active state

Similar to vaadin/vaadin-button#46, the active state is not applied for the checkbox.

Add iron-form validation APIs to <vaadin-checkbox-group>

child of #98
depends on #100

Add iron-form validation APIs to

required
invalid
errorMessage
...

Tabindex doesn't work on Firefox

Try "Checkboxes with Custom Tabindex" demo with Firefox.

Also, there’s both tabindex and tab-index attributes!

Focus-ring gets preserved when activating focusable element in label

Description

When the label slot contains focusable element (<a> might be the most common use case), focus-ring style is still applied to the host element while the focus is in that light DOM element.

Demo

Run this fiddle, hit Tab twice and you will see the focus-ring style on the checkbox with the native outline on the link at the same time.

Default look for indeterminate state doesn't work properly in iOS

iOS Chrome & Safari:

Actual 1: Initially, the indeterminate state looks exactly like the unchecked checkbox.
Expected 1: indeterminate state should be different from checked and unchecked states

Actual 2: After the first tap, the indeterminate checkbox doesn't change its look at all
Expected 2: After the first tap it should be checked

Actual 3: After the second tap, the indeterminate checkbox doesn't change its look at all
Expected 3: After the second tap it should be unchecked

Actual 4: After the third tap, the indeterminate checkbox looks like ugly checked

Expected 4: After the third tap it should be checked

Executing click() on the element does not correctly toggle the state when indeterminate=true

The problem can be seen here: https://cdn.vaadin.com/vaadin-checkbox/2.0.0-alpha7/demo/#checkbox-indeterminate-demos

If you click the "Select all" checkbox, it moves from indeterminate state to checked state.
If you instead find the element in the inspector and call $0.click();, it moves from indeterminate state to unchecked state.

A workaround seems to be to call click(); on the native input element, but you can't easily get a reference to that

Ensure Polymer 3 Modulizer compatibility

See “Generic steps” at vaadin/components-team-tasks#326

Styling problem in IE11

When having multiple checkboxes inside vaadin-checkbox-group, checkboxes go beyond the parent width in IE11.
Same problem exists in vaadin-radio-group.

Label for <vaadin-checkbox-group>

child of #98
depends on #100

Take inspiration from vaadin/vaadin-radio-button#62

Make sure the label also works with Material theme

Incorrect 'aria-checked' attribute value

Description

Incorrect 'aria-checked' attribute value;

Expected outcome

The 'aria-checked' attribute value should be 'mixed'.

Actual outcome

The 'aria-checked' attribute value is 'checked'

Live Demo

https://jsfiddle.net/goranvaadin/4sf4avtm/

Steps to reproduce

1. Set the vaadin-checkbox 'indeterminate' state to 'true'
2. Set the vaadin-checkbox 'checked' state to 'true'

NOTE: If the steps are reversed, then the 'aria-checked' attribute has the correct value of 'mixed'

Browsers Affected

• Chrome

Checkbox group missing has-value attribute and Lumo required indicator

The has-value attribute needs to be implemented. Also, following styles to be added for Lumo:

      :host([required]) [part="label"] {
        padding-right: 1em;
      }
      [part="label"]::after {
        content: var(--lumo-required-field-indicator, "•");
        transition: opacity 0.2s;
        opacity: 0;
        color: var(--lumo-primary-text-color);
        position: absolute;
        right: 0;
        width: 1em;
        text-align: center;
      }
      :host([required]:not([has-value])) [part="label"]::after {
        opacity: 1;
      }

Material theme also needs required indicator.

iron-form update to 2.1.0 breaks serialization tests

The iron-form 2.1.0 was just released and introduced 6 test failures in both Chrome and Firefox:

chrome 62                ✖ test/[secure]_test.html » iron-form-checkbox » should serialize
  expected [ 'on', 'on' ] to equal 'on'

Adding the hidden attribute has no effect

Adding the hidden attribute to a vaadin-checkbox doesn't seem to have any effect. As a user I would expect it to hide the element as if it were a normal input element. See https://jsfiddle.net/ogg9b6tL/ for an example.

Checkbox group MVP

child of #98

• Basic functionality excluding the label and form validation APIs (see the epic for more info)
• Start working on top of <vaadin-radio-group> to keep the internals aligned
• Make sure it's compatible with P3

Annotate the usage of the Polymer.GestureEventListeners mixin, so it can be identified by the Polymer analyzer

Components that use the Polymer.GestureEventListeners mixin should use the @mixes annotation:

@mixes Polymer.GestureEventListeners

That way Polymer analyzer can properly identify the usage of the mixin and tools that depends on the analysis can use that information, such as the webcomponents.org website.

Style changes applied on shadow DOM elements using host attributes do not get repainted on iOS

The Valo theme for checkbox suffers from the same problem as the Material and Valo themes for vaadin-text-field, that the CSS updates on shadow DOM elements, applied using selectors that target host attributes, do not get repainted by the browser (a Safari bug).

One option is to copy a similar hack as used in vaadin-text-field (I verified this to work for Valo theme): https://github.com/vaadin/vaadin-text-field/blob/master/vaadin-text-field.html#L394-L403

A workaround is to toggle some property on the affected elements using the native input element’s state to force other style updates as well, for example (verified to work for the Valo theme):

[part="native-checkbox"]:checked ~ [part="checkbox"] {
  opacity: 1;
}

checked-changed event doesn't have right value

checked-changed event is fired before the checked value is actually changed. Similar to: vaadin/vaadin-date-picker#410

Disabled checkbox get invisible focus state

Reproducible here https://cdn.vaadin.com/vaadin-checkbox/1.0.0-alpha2/demo/index.html

In the situation above I press TAB and expected result is:

Actiual result:

Chrome/Linux

Checkbox group does not validate on focusout

The component must run validation on focusout, same as radio-group does:
https://github.com/vaadin/vaadin-radio-button/blob/004135632bfb2697e366de7b64e4763c9df58f39/src/vaadin-radio-group.html#L212

Currently, when tabbing out from the checkbox group without checking any checkbox, no validation occurs.

Checkbox doesn't work on iPhone

Can't click any checkbox, live demo: http://flow.app.fi/demo-flow-components-0.1.16-SNAPSHOT/vaadin-checkbox

Visual highlight is appearing on disabled checkbox (iOS Safari)

<vaadin-checkbox-group>

Create a <vaadin-checkbox-group> element whose value derives from the <vaadin-checkbox>es wrapped inside of it.

Here's how you'd use the component:

<vaadin-checkbox-group>
  <vaadin-checkbox value="apples"></vaadin-checkbox>
  <vaadin-checkbox value="oranges"></vaadin-checkbox>
  <vaadin-checkbox value="bananas"></vaadin-checkbox>
</vaadin-checkbox-group>

The value of the component should be of type Array consisting of string values of the checkboxes in the similar fashion the <vaadin-radio-group>'s value is derived from the contained <vaadin-radio-button>'s.

Changing the value array should check the matching contained checkboxes and uncheck the ones that don't match.

The <vaadin-checkbox-group> doesn't need special handling for arrow keys like <vaadin-radio-group> does.

Label
Form validation APIs built-in

Inspiration:

• <vaadin-radio-group>
• https://github.com/vaadin/expense-manager-demo/blob/master/src/option-group.html
  • No items array, light-dom api only for now

Remove part from the label element

I’m not really sure why I would need to style the wrapper element. It’s not semantic in any way for the component.

The "will-change" styles hurt scrolling performance in <vaadin-grid>

This is especially evident with Safari. Open https://cdn.vaadin.com/vaadin-grid/5.0.0-alpha3/demo/#grid-selection-demos and try scrolling the grid in "Multi-Selection Column" demo.

Disabling both will-change styles in https://github.com/vaadin/vaadin-checkbox/blob/master/theme/valo/vaadin-checkbox.html fixes the issue.

Space press doesn’t change the intermediate state (Safari)

publish a change event

Currently, it is only possible to detect changes by observing property changes. Would like to see a change event that is only fired as a result of user interaction

Checkbox with no label content is too wide

It seems the :empty pseudo class does not work for the label part, as it always contains the <slot> element: https://github.com/vaadin/vaadin-checkbox/blob/master/theme/lumo/vaadin-checkbox.html#L27-L29

The result is that a plain checkbox (for example the selection checkboxes inside vaadin-grid) take more space than needed.

Material: checkbox group crops the ripple

The contain: content; CSS property crops the ripple of the first checkbox in a row:

Here is the line where it is set on the host element:

vaadin-checkbox/theme/material/vaadin-checkbox-group-styles.html

Line 16 in 1b426d2

contain: content;

Note: only happens in Chrome, and the CSS property is experimental (not supported by Firefox and Safari) so we should remove it for now and consider adding back later.

indeterminate flag should be false by default instead of undefined

False is the default value in native checkbox.

Space press doesn't change the indeterminate state

Reproducible here: https://cdn.vaadin.com/vaadin-checkbox/1.0.0-alpha2/demo/index.html

In the situation above I press space.

• Expected result: checkbox got checked state.
• Actual result: Nothing happens.

Chrome/Linux

Setting the checkbox as indeterminate should clear the checked attribute

Currently it's possible to set a vaadin-checkbox as checked AND indeterminate at the same time.

This leads to some strange behaviors, like clicking on a checkbox which is indeterminate and checked and actually making it unchecked.

In terms of API, when setting the indeterminate attribute/property, the checked attribute/property should be cleared (or set to false).

Example:
When having this:

<vaadin-checkbox id="my-check" checked></vaadin-checkbox>

... and setting this:

document.getElementById("my-check").indeterminate = true;

... we end up with this:

<vaadin-checkbox id="my-check" checked indeterminate></vaadin-checkbox>

... and if the user clicks on it we end up with this:

<vaadin-checkbox id="my-check"></vaadin-checkbox>

There is a counterpart issue on Flow: vaadin/vaadin-checkbox-flow#6

Checkbox group uses the same array instance when value is changed

Checkbox group always uses the same array instance as a value when it's modified.

Expected: Flow client engine expects different values for property when value is updated. Flow doesn't listen changes in array (and Flow doesn't know the exact type of the property value).
Flow has code which compares the current value cached internally with the new value received from web component. If it's the same value then update is ignored and nothing is sent to the server. Since the array instance is the same Flow doesn't update value on the server side.

Actual: the value is always the same array which is just modified.

All browsers affected.
No live demo since I can't create Vaadin Flow Combobox Group component because of this bug and there is no any documentation yet about vaadin-checkbox-group web component with HTML examples.

In Firefox, native checkbox has outline at the same time with a component (when focused)

the `click()` method should toggle the checked property

In the HTML spec exists the click() method as part of the API.
The native checkbox and the paper-checkbox handle the click() call toggling the checked status, vaadin-checkbox should behave the same

Emojis in checkbox’s text will misalign the text from the checkbox.

Emojis in checkbox’s text will misalign the text from the checkbox. Pure text works fine. (Safari). Baseline issue

Native outline appears around the select checkbox on double-click

Chrome/Linux, mouse double-click:

@jouni I believe outline: none should help. Should that be in core styles or in a theme? IMO it should be in core styles since we have the replacement for handling the focus - control-state-mixin.

Doesn't serialize in iron-form

#45 (comment)

It's not clear from the API docs what is label

Mention that label is generated from the light DOM content.

Problem when using checkbox-group inside overlay.

When vaadin-checkbox-group is used inside vaadin-overlay, checkboxes can be checked, but can't be unchecked.

Demonstration:
https://vaadin-overlay-checkbox-group.glitch.me/

Code:
https://glitch.com/edit/#!/vaadin-overlay-checkbox-group

Flow API related todo list

Value compatibility

Make sure all public-available user input elements follow these rules:

• the value property is declared as String
• the value property is not read-only and allows changes
• the value property declaration has notify: true

Validation compatibility

Make sure all public-available validateable elements follow these rules:

• the invalid property is declared as Boolean
• the invalid property has notify: true
• validate() method updates the invalid state property

vaadin-combo-box-mixin.html

• ❓ deprecate open() and close() methods for future removal in next major version, since duplicate of writable opened property
• ❓ deprecate cancel() method for future removal
  • probably duplicate of comboBox.opened = false; comboBox.value = initialValue;
• in validate() and checkValidity() methods, remove the value argument since not in use
• mark with @private and deprecate the hasValue property, only the argument should be kept for styling

vaadin-combo-box.html

• remove the property allowedPattern, since not in use
• make sure the pattern property is used, add tests for it
• remove the property inputmode, since not in use
• remove the property size, since not in use

vaadin-combo-box-light.html

• remove the property overlayVerticalOffset, since not in use in regular <vaadin-combo-box>
• ❓ deprecate required property, validate() and checkValidity() methods, since they alias to validation of the user’s provided input element
  • they should stay in regular <vaadin-combo-box>, however

Mark with @private for the element classes

• vaadin-combo-box-dropdown-wrapper.html:
  • class ComboBoxOverlayElement
• vaadin-combo-box-dropdown.html:
  • class VaadinComboBoxOverlay
  • class DropdownElement
• vaadin-combo-box-item.html
  • class ComboBoxItemElement

Non-native default theme

Because of #38 and the fact that I would like to not expose the native input for styling, we should consider having a non-native default theme, and core styles that hide the native input and layout the checkbox and the label content nicely by default.

Not working with iron-form

https://jsbin.com/ziqayus/edit?html,console,output

vaadin-checkbox shows the same value with iron-form's serializeForm() output regardless of whether it is checked or not.

checked-changed event fired on page load

The function is called even though I have not clicked on anything

<dom-module id="test-check">

      <template>
        <vaadin-checkbox on-checked-changed="_changeCheck">asd</vaadin-checkbox>
      </template>

      <script>
        class TestCheck extends Polymer.Element {
          static get is() { return 'test-check'; }

          _changeCheck() {
            console.log('Gets fired on page load');
          }
        }

        window.customElements.define(TestCheck.is, TestCheck);
      </script>

    </dom-module>

    <test-check></test-check>

In IE11 it takes two clicks to get out from indeterminate state

Live demo: https://www.webcomponents.org/element/vaadin/vaadin-checkbox/v2.0.0-alpha4

Should we include the `tabindex` to the API documentation?

Some people don't know about tabindex, they are trying to search the "focus" keyword on the docs page, but without any luck.

on-checked-changed fires when component is initialized

<vaadin-checkbox on-checked-changed="selectAll"></vaadin-checkbox>

The above calls selectAll() immediately on load, which screws up a lot of things.

Links inside vaadin-checkbox content don't work

vaadin-checkbox hijacks the clicks so you can't do something like this:

<vaadin-checkbox>
  I agree to the <a href="/tos">Terms of Service</a>
</vaadin-checkbox>

Here's a simplified test case: https://jsfiddle.net/Haprog/jLrt0cmy/

It would be great if links just worked inside the checkbox so that you can still (un)check the checkbox by clicking on any plain text (or other content) in the checkbox except for links (and maybe buttons?) but clicking on the link would navigate to the link as expected.

Disabled native checkbox missing top border-line

iOS11 Chrome & Safari