z-checkbox

A styled checkbox component for your web application.

Table of contents

• z-checkbox
• Table of contents
• Install
  • Import as HTML/CSS component
  • Import as Stateless Functional Component (SFC)
• How to use
  • CSS component
  • Stateless Functional Component
• Theming
• License

Install

The package is available to download through npm:

npm install z-checkbox --save

Import as HTML/CSS component

The simple case

The package will be located inside the node_modules folder, you can import it into the HTML document as follows:

<link rel="stylesheet" href="node_modules/z-checkbox/dist/style.css">

When bundling an web app

For bundlers that support CSS, like Webpack, you can use it like this:

require('z-checkbox/dist/style.css');

Import as a Stateless Functional Component (SFC)

The package does not include the renderer, you can use any renderer that supports SFCs. You could use React, Preact, Inferno, etc.

Notice: This package contains CSS styling, you may need a bundler that's capable of requiring CSS files like Webpack with css-loader.

Once you have chosen the renderer you can include the package in your project as follows:

// Assuming the React renderer is being used
const React = require('react');
const render = require('react-dom').render;

// Passing the render function when importing
const ZCheckbox = require('z-checkbox')(React.createElement);

// Render it on page, using JSX here :)
render(<ZCheckbox />, document.body);

How to use

CSS component

Just add the HTML structure and CSS classes to reproduce the UI component.

Class hierarchy

| Recommended HTML tags | Parent | Class | Description | Type | | --------------------------------------- | ----------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | div | root | .z-checkbox | Root container | Block | | div | .z-checkbox | .z-checkbox__box | The box containing the checkbox | Element | | input of type checkbox | .z-checkbox__box | .z-checkbox__input | The standard HTML checkbox input | Element | | div | .z-checkbox__box | .z-checkbox__container | The visually styled checkbox that the user sees | Element | | Any containing .z-checkbox__container | .z-checkbox__container--secondary | .z-checkbox__container | Change the background color of the the checkbox to the secondary color | Modifier | | Any containing .z-checkbox__container | .z-checkbox__container--success | .z-checkbox__container | Change the background color of the the checkbox to green | Modifier | | Any containing .z-checkbox__container | .z-checkbox__container--warning | .z-checkbox__container | Change the background color of the the checkbox to yellow | Modifier | | Any containing .z-checkbox__container | .z-checkbox__container--error | .z-checkbox__container | Change the background color of the the checkbox to red, useful for errors | Modifier | | Any containing .z-checkbox__container | .z-checkbox__container--danger | .z-checkbox__container | Change the background color of the the checkbox to a lighter red | Modifier | | label | .z-checkbox | .z-checkbox__label | The optional label that describes the checkbox, the default position is on the right side of the .z-checkbox__box element | Element | | Any containing .z-checkbox__label | .z-checkbox | .z-checkbox__label--top | Change the label position to be above the .z-checkbox__box element, label must be declared before the .z-checkbox__box element | Modifier | | Any containing .z-checkbox__label | .z-checkbox | .z-checkbox__label--left | Change the label position to be on the left side of the .z-checkbox__box element, label must be declared before the .z-checkbox__box element | Modifier | | Any containing .z-checkbox__label | .z-checkbox | .z-checkbox__label--bottom | Change the label position to be below the .z-checkbox__box element, label must be declared after the .z-checkbox__box element | Modifier |

Full working example:

<div class="z-checkbox">
  <div class="z-checkbox__box">
    <input id="example" type="checkbox" class="z-checkbox__input">
    <div class="z-checkbox__container"></div>
  </div>
  <label for="example" class="z-checkbox__label">Example checkbox</label>
</div>

Stateless Functional Component

Render the HTML by using the SFC and passing props.

Supported Props

| Prop name | Expected Type | Description | | --------------- | ------------- | ----------------------------------------------------------------------------------- | | label | string | The text description of the checkbox | | labelPosition | string | Pass top, left or bottom to change the label position, the default is right | | secondary | boolean | Change the background color of the checkbox to the secondary color | | success | boolean | Change the background color of the checkbox to green | | warning | boolean | Change the background color of the checkbox to yellow | | error | boolean | Change the background color of the checkbox to red, useful for errors | | danger | boolean | Change the background color of the checkbox to a lighter red |

Note: You can pass any input attribute to ZCheckbox, like disabled, checked and so on, it will pass through.

Full example (JSX):

<ZCheckbox id="example" label="Label" labelPosition="top" />

Theming

1.2.0 version of z-checkbox brings theming support via CSS Variables.

Below is the list of variables available to use:

| Variable | Expected type | Description | | ---------------------- | ------------------- | ----------------------------------------------------- | | --primary-color | color | The primary background-color of the checkbox | | --secondary-color | color | The secondary background-color of the checkbox | | --success-color | color | A success indicating background-color of the checkbox | | --warning-color | color | A warning indicating background-color of the checkbox | | --danger-color | color | A danger indicating background-color of the checkbox | | --error-color | color | An error indicating background-color of the checkbox | | --neutral-border-color | color | The default border-color of the checkbox | | --focused-border-color | color | The border-color of the focused checkbox | | --checkbox-label-color | color | The color of the checkbox label text | | --checkbox-size | px, em or rem | The size of the ticker box, always squared |

LICENSE

MIT