README

Component Library

Contents

Overview
Getting Started
Usage
- End User
- Theme Builder
Components

Overview

This package is a library of react components focused on accessibility and progressive enhancement. When used with a server-side-rendered react application, these components remain functional for users who may not have javascript or css available.

Getting Started

Install the package:

npm i @button-inc/component-library or yarn add @button-inc/component-library

Import component(s):

import Button from @button-inc/component-library/Button

For themed components, you can add @button-inc/bcgov-theme or @button-inc/button-theme.

If you want to build your own theme, see below for instructions. There is also a live playground to test it out.

Building a Theme

As a theme builder, you can add custom styles to the components through an applyTheme function. For any component in the library, this function can be imported as a named import, e.g:

import { applyTheme } from '@button-inc/component-library/Button';

This function can be called with a styles object and a config object to theme the base component:

const ThemedButton = applyTheme(styles, config);

Styles

The styles argument defines the props that end-users can use to style their component. For any prop you want to support, create a key with that name. For example, to support a primary style and secondary style:

const styles = {
  primary: {
    ...
  },
  secondary: {
    ...
  }
}

Note: We support syntax <Button primary> and <Button variant='primary' />. See prop values for how to implement each style.

The value of the key is an object that will set the css for the component. Each component has subsections which can be styled independently. For example, an <input> component is comprised of a container, a label, and the actual input. Apply the css for each section with the section's name as a key:

const styles = {
  primary: {
    container: `
      background-color: blue;
    `,
    input: `
      color: green;
    `,
    label: `
      font-size: 10px;
    `
  },
  secondary: {
    container: `
      background-color: blue;
    `,
    input: `
      color: yellow;
    `,
    label: `
      font-size: 10px;
    `
  }
}

See components for the list of sections that can be styled for each component. It will often be the case that you have a core set of styles that will apply to all variants of your component. In the example above, only the input's color property is changing. To reduce re-writing these styles, you can include them in the shared property:

const styles = {
  shared: {
    container: `
      background-color: blue;
    `,
    label: `
      font-size: 10px;
    `
  },
  primary: {
    input: `
      color: green;
    `
  },
  secondary: {
    input: `
      color: yellow;
    `
  }
}

Prop Values

Props can have either boolean values, string values, or a mix of both. If the key's value is an object styling the components subsections, it will be treated as a boolean value. E.g:

const styles = {
  primary: {
    container: `
      ...
    `
  }
}

Will support the end user syntax <Component primary>. If you want a prop to have a string value, e.g <Component variant='primary'>, add the different options as keys of the prop with their own css definitions:

const styles = {
  variant: {
    primary: {
      container: `
        ...
      `
    },
    secondary: {
      container: `
        ...
      `
    }
  }
}

SCSS

This library is built on top of styled-components, and supports any scss style syntax they do. See pseudoelements pseudoselectors and nesting for more information.

Config

The config argument can be used to set default properties and static properties on an element. Default properties will be applied to a component that has no definition for that prop. For example:

const config = {
  defaultProps: {
    variant: 'primary'
  }
};

Will give the component a variant=primary style if the variant isn't set. Additionally the config object can set static props, which currently support fullHeight and fullWidth. Use these if you want the component to take up 100% of it's parent by default:

const config = {
  staticProps: ['fullHeight']
};

Components

Component	Stylable Sections	Takes Children
Button	button	Yes
Checkbox	container input label checkmark	No
DatePicker	container input label	No
Fieldset	container legend	Yes
Footer	container footer	Yes
Input	container label input	No
Menu	container group item	Yes
Navigation	container toggle sidebar	Yes
Notification	container header content group close	Yes
RadioButton	container input label dot	No
Select	container input label wrapper	Yes
Textarea	container input label	No

Usage no npm install needed!