Blackbox React npm

Design systems aim to streamline the design and development process by providing pre-built components and modules that are modular, reusable, consistent, customizable, and relevant.

Blackbox is Propelrr's single source of truth.

View on Github

Components

Accordion

import Accordion from 'blackbox-react/accordion'

Examples

Standard Use

Default State

Open the accordion by default

Answer here...

Color

Set the active color of the accordion for the icon and borders

Font

Set the font style for the title

Custom Icons

Set the open and close icon or text

Remove Border

Remove the border from the accordion

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Containing element
  • head
    • Header container
  • toggle
    • Header icon
  • title
    • Header title text
  • body
    • Content body

For example:

Button

import Button from 'blackbox-react/button'

Examples

Tag

Specify the tag or component e.g. a, button, Link etc.

I'm an <a> tagI'm a <span>

Colors

Change the background color to one of the theme's colors

Change the foreground color to one of the theme's colors

Size

Alter the font size, using a factor to be passed into the scale function

Spacing

Change the padding of the button by passing in a spacing object or number

Border

Set the border width (px) and/or color to one of the theme's colors

Outline

Border Radius

Fonts

Specify a specific font treatment

Hover Effects

Set the hover effect of the button

Custom Styles

Pass in custom style rules to be applied to the button

Treatments

The following treatments in your project's traits will be applied:

  • button

ButtonGroup

import ButtonGroup from 'blackbox-react/button-group'

Examples

Standard Use

Spacing

Adjust the spacing between buttons using a spacing object or a number

Custom Styles

Pass in custom style rules to be applied to the group

ButtonShare

import ButtonShare from 'blackbox-react/button-share'

Uses the Button component to create a share button with an icon. Renamed from ButtonSocial in v2.1

Will accept any props that the Button accepts

Carousel

import Carousel from 'blackbox-react/carousel'

Depends on react-slick. See README for full list of available options.


Examples

Standard Use

Slide 1

Autoplay

Slide 1

Custom Styles

Pass in custom style rules to be applied to the carousel

Slide 1

Flippy

import Flippy from 'blackbox-react/flippy'

Examples

Standard Use

Hover to see more...

Peekaboo!

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Wrapper element
  • wrapper
    • Common styles shared by front and back
  • front
    • Content seen initially
  • back
    • Content seen on hover
This is the front...

And this is the back!

Heading

import Heading from 'blackbox-react/heading'

Examples

Standard Use

Provides a standard format for page/section headings

Heading 1

Color

Heading 1

Custom Styles

Pass in custom style rules to be applied to the heading

Heading 1

Icon

import Icon from 'blackbox-react/icon'

Examples

Available Icons

Social / Providers

Colors

Spin

Rotate

Custom Icon

Custom SVG viewbox size

Button

Custom Styles

Image

import Image from 'blackbox-react/image'

Examples

Standard Use

Example Image

LazyImage

import LazyImage from 'blackbox-react/lazy-image'

Render a colored square with a loading spinner in place of an image whilst it's being loaded.

Useful to prevent a layout from breaking, flickering or changing size during a page load.

Examples

Standard Use

Pass a url to an image

With a custom size and background color

With a custom loading spinner

Loading...

With lazy loading and a callback

Loading

import Loading from 'blackbox-react/loading'

Examples

Standard Use

Custom parameters

Meta

import Meta from 'blackbox-react/meta'

Provides a consistent API wrapper around React Helmet for page meta

Standard Use

import { Meta } from "blackbox-react";

<Meta
  title='Page title'
  description='Lorem ipsum dolor sit amet, consectetur adipisicing elit.'
/>

Modal

import Modal from 'blackbox-react/modal'

Uses React Modal - https://github.com/reactjs/react-modal

Examples

Standard Use

Example of a component that opens a modal when a button is clicked

Example Using Toggle

Example using the withToggle higher order component

Custom Example

Contains some custom spacing, styles and close button

NumberToWords

import NumberToWords from 'blackbox-react/number-to-words'

NumberToWords is a wrapper component around the numberToWords function

It converts a number between 0 and 1,000,000,000 to words and forwards the props to the wrapping element

Example

zero
one thousand three hundred and thirty-seven
forty-two

four million and four

ProgressBar

import ProgressBar from 'blackbox-react/progress-bar'

Examples

Standard Use

A half filled progress bar.

50% raised

Using traits

Uses custom colors and radiuses as specified by traits

50% raised

Custom styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Container
  • fill
    • Progress fill

For example, using a gradient for the progress fill:

50% raised

RichText

import RichText from 'blackbox-react/rich-text'

Examples

Standard Use

Provides a standard format for chunks of markup

Heading 1

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Heading 2

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Heading 3

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.

Heading 4

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

  • Donec id elit non mi porta gravida at eget metus. Etiam porta sem malesuada magna mollis euismod. Vestibulum id ligula porta felis euismod semper.
  • Donec id elit non mi porta gravida at eget metus. Etiam porta sem malesuada magna mollis euismod. Vestibulum id ligula porta felis euismod semper.
  • Donec id elit non mi porta gravida at eget metus. Etiam porta sem malesuada magna mollis euismod. Vestibulum id ligula porta felis euismod semper.
Heading 5

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

  1. List item 1
  2. List item 2
  3. List item 3
Heading 6

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Font Size

Heading 2

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Line Clamp

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Custom Styles

You can pass through custom styles to be applied

Heading 1

Donec id elit non mi porta gravida at eget metus. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas sed diam eget risus varius blandit sit amet non magna. Etiam porta sem malesuada magna mollis euismod.

Ticker

import Ticker from 'blackbox-react/ticker'

Examples

Standard Use

  • Person A: $50
  • Person B: $150
  • Person C: $10
  • Person A: $50
  • Person B: $150
  • Person C: $10
  • Person A: $50
  • Person B: $150
  • Person C: $10
Latest Donations

Custom speed / colours

  • Person A: $50
  • Person B: $150
  • Person C: $10
  • Person A: $50
  • Person B: $150
  • Person C: $10
  • Person A: $50
  • Person B: $150
  • Person C: $10

Tooltip

import Tooltip from 'blackbox-react/tooltip'

The only prop, the child function, is called with three parameters

bindTarget - An object containing a ref assignment and event listeners for dectecting hover events. Spread this argument onto the node that you want to be the hover target

TooltipPortal - A component that renders its children in a portal when the target from the previous parameter is being hovered. To Make sure the tooltip stays open when hovering over the portal content, make sure it is rendered inside the target node

tooltipStyles - A style object containing the top and left value of the target node and some basic transforms, forward this to the root node of your TooltipPortal

Examples

Standard Use

Hover over me!

Forms

Filter

import Filter from 'blackbox-react/filter'

Examples

Standard Use

Pass an onChange callback to be notified of changes

Disable Debounce

We can turn the debouncing off if required

Colors

Update the background and foreground colors

This is useful for when the form is on a different color background already

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Form styles
  • icon
    • Search icon
  • input
    • The search field

Form

import Form from 'blackbox-react/form'

Examples

Standard Use

Pass an onSubmit callback to be notified of changes

With additional form actions

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Form styles
  • fields
    • Form fields wrapper
  • error
    • Error message
  • action
    • Form actions group
  • action
    • Form action
  • submit
    • Submit button
  • icon
    • Submit button icon

Treatments

The following treatments in your project's traits will be applied:

  • form -> root
  • formError -> error
  • formAction -> action
  • formSubmit -> submit

InputField

import InputField from 'blackbox-react/input-field'

Examples

Standard Use

Pass an onChange callback to be notified of changes

Status indicator

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Containing element
  • field
    • Input element
  • label
    • Label element
  • required
    • Required label (if present)
  • errors
    • Error messages container
  • error
    • Error message styles
  • status
    • Status indicator styles

For example:

Treatments

The following treatments in your project's traits will be applied:

  • inputRoot -> root
  • input -> field

InputSelect

import InputSelect from 'blackbox-react/input-select'

Examples

Standard Use

Pass an onChange callback to be notified of changes

Grouped Options

Includes support for <optgroup>

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Containing element
  • wrapper
    • Wrapper around hidden select element and UI placeholder
  • input
    • Select field (UI hidden)
  • field
    • Field UI element (placeholder)
  • label
    • Label element
  • required
    • Required label (if present)
  • icon
    • dropdown icon
  • errors
    • Error messages container
  • error
    • Error message styles

Treatments

The following treatments in your project's traits will be applied:

  • inputRoot -> root
  • input -> field

InputDate

import InputDate from 'blackbox-react/input-date'

Examples

Standard Use

Pass an onChange callback to be notified of changes

No date selected

Always show selects

No date selected

Predefined date

InputSearch

import InputSearch from 'blackbox-react/input-search'

Examples

Standard Use

You can use the InputSearch component to filter through a known data set

Asynchronous Data

You can also use it to perform API requests to fetch relevant results

withForm

Like other Constructicon input components, the InputSearch props are designed to play well with the withForm higher order component

Form Values: {"city":""}

Treatments

The following treatments in your project's traits will be applied:

  • inputRoot -> root
  • input -> field

InputSearchResult

import InputSearchResult from 'blackbox-react/input-search-result'

Examples

Handles common highlight of active and hovered search results

Standard Use

Search result name 1
Search result name 2
Search result name 3

InputFile

import InputFile from 'blackbox-react/input-file'

Examples

Standard Use

Multiple files

Treatments

The following treatments in your project's traits will be applied:

  • inputRoot -> root
  • input -> field

InputValidations

import InputValidations from 'blackbox-react/input-validations'

Examples

Standard Use

Field is required

Custom styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Label element
  • error
    • Individual error strings
Field is required

Treatments

The following treatments in your project's traits will be applied:

  • inputValidations -> root
  • inputValidation -> error

Label

import Label from 'blackbox-react/label'

Examples

Standard Use

Required

Custom styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Label element
  • required
    • Required label (if present)

Treatments

The following treatments in your project's traits will be applied:

  • label -> root

SearchForm

import SearchForm from 'blackbox-react/search-form'

Examples

Standard Use

Expanded

With Search Results

Custom styles

Apply a custom styles object to alter the look. Available elements are:

  • root
  • form
  • field
  • input
  • label
  • results

Layout

Container

import Container from 'blackbox-react/container'

Examples

Standard Use

Used to contain site content within a centered and minimum width container

Header
Body
Footer

Width

Alter the minimum width of the container

Header
Body
Footer

Shadow

Apply one of the theme's shadows to the container

Header
Body
Footer

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root: Root content element
  • outer: Wrapper element
Hello!

Grid

import Grid from 'blackbox-react/grid'

Examples

See below in the GridColumn component

Custom Styles

Pass in custom style rules to be applied to the grid

GridColumn

import GridColumn from 'blackbox-react/grid-column'

Examples

Simple Responsive Grid

Simple main content and sidebar style grid that snaps into single column on smaller screens

Column 1
Column 2

Custom Styles

Pass in custom style rules to be applied to the grid column

Section

import Section from 'blackbox-react/section'

Examples

Standard Use

Used to apply consistent padding to sections of content

Content here

Spacing

Adjust the spacing by passing in a spacing object or a number

Content here

Colors

Set the background and/or foreground colors of the section to one of theme's colors

Content here

Borders

Set the border width, border color and/or border radius

Content here

Custom styles

Pass in custom style rules to be applied to the section

Content here

Pages

Pagination

import Pagination from 'blackbox-react/pagination'

Pagination is a component with a render-prop to control the pagination of an array

It splits the provided array (toPaginate) into chunks of max length and invokes the child render-prop with a set of pagination controls.

Usage

The child function supplied to Pagination, will receive one argument, an object with the following shape.

allPages - array - the entire chunked array of arrays

currentPage - array - the currently active 'page' array

numberOfPages - number - the length of the allPages array

pageIndex - number - index of currentPage in allPages (starting at 0)

pageNumber - number - human readable number of currentPage in allPages (starting at 1)

pageOf - string - human readable string of your current page "page 1 of 2"

isPaginated - boolean - true if allPages contains more than one item

canNext - boolean - true if you are not on the last page

canPrev - boolean - true if you are not on the first page

next - function - change currentPage to the next page in the list

prev - function - change currentPage to the previous page in the list

Example

Leaderboard

import Leaderboard from 'blackbox-react/leaderboard'

Examples

Standard Use

Colors

Set the background and foreground color of the leaderboard

Columns

Set the leaderboard to break into columns at certain breakpoints

Loading

Set the loading prop while your results are loading

Error

Set the error prop if there was an error loading the leaders

There was an error loading the results

Empty

If the no leaderboard items are passed in, an empty message will be shown

No results found

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Containing element
  • leaders
    • Applied to the leaders listing

Treatments

The following treatments in your project's traits will be applied:

  • leaderboard -> root
  • leaderboardState -> state
  • leaderboardLeaders -> leaders

LeaderboardItem

import LeaderboardItem from 'blackbox-react/leaderboard-item'

Examples

Standard Use

Custom Link Component

  1. Name Here
    Name Here
    Charity Name
    2,500km

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • the list item
  • link
    • the anchor tag
  • image
    • the avatar
  • info
    • the title and subtitle container
  • title
    • the main name or title
  • subtitle
    • the subtitle or charity
  • amount
    • the amount

Treatments

The following treatments in your project's traits will be applied:

  • leaderboardItem -> root
  • leaderboardItemImage -> image
  • leaderboardItemTitle -> title
  • leaderboardItemSubtitle -> subtitle
  • leaderboardItemAmount -> amount

Metric

import Metric from 'blackbox-react/metric'

Examples

Standard Use

Target
$500,000

Custom Styles

Apply a custom styles object to alter the look. Available elements are:

  • root
    • Container element
  • icon
    • Icon
  • label
    • Label / Heading
  • amount
    • Metric value

Treatments

The following treatments in your project's traits will be applied:

  • metric -> root
  • metricLabel -> image
  • metricAmount -> amount
  • metricIcon -> icon

MetricGroup

import MetricGroup from 'blackbox-react/metric-group'

Example Use

Standard Use

Target
$500,000
Funds Raised
$250,000
Supporters
174

Colors

Set the background and/or foreground colors

Target
$500,000
Funds Raised
$250,000
Supporters
174

Custom Styles

Pass in custom style rules to be applied to the group

Target
$500,000

SearchResults

import SearchResults from 'blackbox-react/search-results'

Examples

Loading

Set the loading prop while your results are loading

Error

Set the error prop if there was an error loading the leaders

There was an error loading the results

Empty

If the no leaderboard items are passed in, an empty message will be shown

No results found

Results

Filled with SearchResults

  • Support Name

    Support Name

    Supporter Charity
  • Support Name

    Support Name

    Supporter Charity

Custom styles

Apply a custom styles object to alter the look. Available elements are:

  • root
  • state
  • loading

SearchResult

import SearchResult from 'blackbox-react/search-result'

Examples

Standard Use

Provides a list item suited for a search results listing.

  • Support Name

    Support Name

    Supporter Charity

    • Custom styles

    Apply a custom styles object to alter the look. Available elements are:

    • root
    • avatar
    • titles
    • title
    • subtitle

    Scripts

    Typekit

    import Typekit from 'blackbox-react/typekit'

    Examples

    Standard Use

    Theming

    TraitsProvider

    import TraitsProvider from 'blackbox-react/traits-provider'

    Example

    Standard Use

    Pass in a traits object to set the various available traits, including:

    colors

    primary, secondary, tertiary, dark, light, shade, tint

    fonts

    head, body

    treatments

    head, body, button

    radiuses

    small, medium, large

    shadows

    light

    effects

    shade, tint, grow, shrink

    import { TraitsProvider, ButtonGroup, Button } from "blackbox-react";

const fonts = {
  head: 'Roboto',
  body: 'Roboto'
};

const traits = {
  fonts,
  colors: {
    primary: '#42AA4C',
    secondary: '#096010',
    tertiary: '#585858'
  },
  treatments: {
    head: {
      fontFamily: fonts.head,
      fontWeight: 700
    },
    body: {
      fontFamily: fonts.body
    },
    button: {
      fontFamily: fonts.head,
      fontWeight: 700,
      textTransform: 'uppercase'
    }
  }
};

<TraitsProvider traits={traits}>
  <ButtonGroup>
    <Button>Click Me</Button>
    <Button background='secondary'>Click Me</Button>
  </ButtonGroup>
</TraitsProvider>

    Higher Order Components

    withForm

    Example components can be found in source/components/with-form/examples

    withForm is a higher order component (HOC) that allows you to pass in your form configuration, and it will then inject a form prop into your component.

    You can then use this form prop, and spread them across InputField or other form fields, and it will handle all the updating and validating of your form.

    You can then call form.submit() when you want to submit your form.


    Form Configuration

    You pass in your form configuration as an object to withForm, with all your fields passed in under the fields key.

    Each field can be passed in a number of properties:

    label - the label for the field

    initial - the initial value of the field (empty if not applicable)

    validators - a function, or array of functions that will validate the field

    type, placeholder - or any other attribute that you want spread onto the dom element


    Validators

    The validators you pass in are functions that take 2 args:

    value - the current value of the field

    values - the current values of all fields, useful if your validation is conditional

    These functions should return a falsy value if valid, and an error message if invalid.

    There are some predefined validators you can use in constructicon/lib/validators


    Example Configuration

    withForm({
  fields: {
    email: {
      label: 'Email',
      validators: [
        validators.required('Email is a required field'),
        validators.email('Should be a valid email')
      ]
    },
    password: {
      label: 'Password',
      type: 'password',
      validators: validators.required('Password is a required field')
    }
  }
})(MyFormComponent)

    You can also specify an onFormChange listener in the configuration, which takes the form object as an argument

    For example:

    withForm({
  onFormChange: (form) => console.log(form.values, form.invalid, ...),
  fields: {
    // ...
  }
})

    If you wish to pass this in as a prop to your wrapped component, you can supply a function to the withForm HOC, which takes a props argument:

    withForm((props) => ({
  onFormChange: props.onChange,
  fields: {
    // ...
  }
}))

    Form Props

    withForm will pass a form prop into your component.


    form.fields

    You can spread the individual fields across form components. This will pass through all the needed props to that form component, such as onChange handlers.

    <InputField {...form.fields.username} />

    form.updateValues

    You can call form.updateValues() which can update the values of fields from outside user interaction.

    Values can be updated in the format below:

    componentDidUpdate (nextProps) {
  const { testValue } = nextProps
  if (testValue !=== this.props.testValue)
    this.props.form.updateValues({
      testValue: testValue
    })
  }
}

    form.resetForm

    You can call form.resetForm() which will reset all of the form values and validations to their initial state.

    handleCancel () {
  this.props.form.resetForm()
}

    form.submit

    You can call form.submit() which will return a promise that will either:

    Resolve to the field values if valid, or...

    Reject with the invalid fields and there error messages.

    handleSubmit (e) {
  e.preventDefault()
  this.props.form.submit()
    .then((values) => doSomethingGoodWithValues(values))
    .catch((errors) => doSomethingGoodWithErrors(errors))
}

    withToggle

    A very simple higher order component that handles basic toggle functionality.

    withToggle will inject a few useful props into your component:

    toggled the current state of the toggle

    onToggleOn turn the toggle on

    onToggleOff turn the toggle off

    onToggle toggle the value to on/off

    Example

    const MyComponent = ({
  toggled,
  onToggleOn,
  onToggleOff
}) => (
  <div>
    <Button onClick={onToggleOn}>Open</Button>
    <Modal onRequestClose={onToggleOff} isOpen={toggled}>
      I will be shown when the button is clicked
    </Modal>
  </div>
)

export default withToggle(MyComponent)

    Blackbox React Components Library