balena-io-modules / rendition

balena-io-modules

A library of React UI components

150 Stars 29 Forks Last release: Not found Apache License 2.0 2.0K Commits 589 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Readme

Rendition

Name: rendition
Brand: rendition
SKU: //balena-io-modules/rendition
Rating: 2.125 (150 reviews)

A library of UI components, built using React, recompose, styled-components and styled-system.

Installation

npm install --save rendition

Usage

Wrap your application in the

Provider

component and start using components!

import React from 'react'
import ReactDOM from 'react-dom'
import { Button, Box, Provider } from 'rendition';

ReactDOM.render(
  
    
      Click me
    
  ,
  document.getElementById('root')
);

Components

For an interactive demo of all components, see https://balena-io-modules.github.io/rendition

Accordion

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

items

[{label: string \| node; panel: string \| node }]

| - | true | renders label as title and panel as body of accordion |

Alert

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

primary

boolean

| - | - | If true, use the

primary

theme color | |

secondary

boolean

| - | - | If true, use the

secondary

theme color | |

tertiary

boolean

| - | - | If true, use the

tertiary

theme color | |

quarternary

boolean

| - | - | If true, use the

quarternary

theme color | |

danger

boolean

| - | - | If true, use the

danger

theme color | |

warning

boolean

| - | - | If true, use the

warning

theme color | |

success

boolean

| - | - | If true, use the

success

theme color | |

info

boolean

| - | - | If true, use the

info

theme color | |

emphasized

boolean

| - | - | If true, use the use bolder colors and a larger size | |

plaintext

boolean

| - | - | If true, the alert will be rendered without a border or a background | |

prefix

onDismiss

() => void

| - | - | A function that is called when dismissing an alert

ArcSlider

A slider input that is displayed as an arc. This component will scale in size to fit it's container. A label can be added by placing a child element inside this component.

View story source

Props

| Name | Type | Default | Required | Description | | --------------|-----------|-----------|------------|-------------------------------------------------------------- | |

onValueChange

(value: number) => void

| - | - | A function that is called when the slider value changes, this will always be a value between 0 and 1 | |

value

number

| - | - | A number between 0 and 1 that represents the progress | |

fillColor

string

| - | - | A CSS color string to use for the color of the "filled" part of the arc | |

background

string

| - | - | A CSS color string to use for the color of the arc track |

Inheritance

The properties of the

Box

component are also available.

Avatar

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

firstName

string

| - | - | If defined only the first letter will be taken and shown | |

lastName

string

| - | - | If defined only the first letter will be taken and shown | |

src

string

| - | - | URL or base64 encoded image to be displayed in the avatar | |

emphasized

boolean

| false | - | If true, uses a larger size avatar |

Badge

Badges should be used to present data that is not generated by the user (otherwise, tags should be used). The badge can use any of the pre-defined shades, from which the background and text color are generated.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

shade

number

| - | - | The index for one of the pre-determined shades for the badge | |

children

string

| - | ✓ | The text to display inside the badge |

Banner

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

backgroundImage

string

| - | - | The path to an image that should be displayed in the background | |

minHeight

string

| - | - | The minimum height of the

Banner

, eg

180px

Box

Displays a block level element.

The basic building block of a rendition application.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

flex

flex

, if the value is an array, sets a responsive style corresponding to the theme's breakpoints |

order

order

, if the value is an array, sets a responsive style corresponding to the theme's breakpoints

Button

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

primary

boolean

| - | - | If true, use the

primary

theme color | |

secondary

boolean

| - | - | If true, use the

secondary

theme color | |

tertiary

boolean

| - | - | If true, use the

tertiary

theme color | |

quarternary

boolean

| - | - | If true, use the

quarternary

theme color | |

danger

boolean

| - | - | If true, use the

danger

theme color | |

warning

boolean

| - | - | If true, use the

warning

theme color | |

success

boolean

| - | - | If true, use the

success

theme color | |

info

boolean

| - | - | If true, use the

info

theme color | |

light

boolean

| - | - | If true, use white background and default text color | |

disabled

boolean

| - | - | If true, disabled the button | |

outline

boolean

| - | - | If true, the button will have a transparent background, and the border and text color will match | |

plain

boolean

| - | - | If true, render the button without padding, background or border | |

underline

boolean

| - | - | Similar to the

plaintext

prop, but displays a line underneath the button text | |

icon

JSX.Element

| - | - | Optionally provide a JSX element that will be rendered before the text inside the button | |

compact

boolean[]

| [false] | - | Optionally renders the label according to the value inside the array for each breakpoint |

ButtonGroup

Wrapper for buttons to make them stick together.

View story source

Card

Section containing content and actions on the same topic.

View story source

Props

| Name | Type | Default | Required | Description | | -------|--------|-----------|------------|-------------- | |

title

string

| - | - | The title of the card | |

cta

JSX.Element

| - | - | React component added to the header | |

rows

JSX.Element[]

| - | - | Subsections separated by a horizontal separator | |

minHeight

string

auto

| - | CSS minHeight property | |

small

boolean

| - | - | If true, reduces the scale of the card | |

children

JSX.Element

| - | - | Any content that is internally wrapped in a Box |

Checkbox

View story source

Props

Checkbox

implements all properties from Grommet's CheckBox component

Container

A padded container with a responsive width.

View story source

Copy

Wrapper that adds a "copy to clipboard" button to any component and copies the passed content to the user's clipboard.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

content

string

| - | ✓ | The value that should be copied to the clipboard |

show

onClick

(content: string) => void

| - | - | onClick handler, useful if you wish to do other actions after content was copied |

children

React.ReactNode

| - | - | The content next to which the clipboard button should be shown

Divider

A styled horizontal rule.

View story source

Props

| Name | Type | Default | Required | Description | | -------|--------|-----------|------------|-------------- | |

height

number

0.5

| - | The height of the divider | |

color

string

quartenary.main

| - | The color of the divider | |

type

'solid' | 'dashed'

'solid

| - | The type of divider | |

children

string

| - | - | Textual explanation to go in the middle of the divider |

DropDownButton

Displays a button with an attached dropdown list,

children

of the component are rendered inside a dropdown list.

View story source

Props

| Name | Type | Default | Required | Description | | ------------- | ------ | --------- | ---------- | ------------- | |

primary

boolean

| - | - | If true, use the

primary

theme color | |

secondary

boolean

| - | - | If true, use the

secondary

theme color | |

tertiary

boolean

| - | - | If true, use the

tertiary

theme color | |

quarternary

boolean

| - | - | If true, use the

quarternary

theme color | |

danger

boolean

| - | - | If true, use the

danger

theme color | |

warning

boolean

| - | - | If true, use the

warning

theme color | |

success

boolean

| - | - | If true, use the

success

theme color | |

info

boolean

| - | - | If true, use the

info

theme color | |

emphasized

boolean

| - | - | If true, use a larger size | |

square

boolean

| - | - | If true, render the button with equal length width and height | |

disabled

boolean

| - | - | If true, disabled the button | |

label

JSX.Element

| - | - | Optionally provide a JSX element that will be displayed inside the main button | |

border

boolean

| - | - | If true, place a border between each item in the dropdown | |

joined

boolean

| - | - | If true, render the component as a single button instead of two | |

noListFormat

boolean

| - | - | If true, render children as a single JSX element instead of iterating over each of them | |

alignRight

boolean

| - | - | If true, put the dropdown list on the right | |

listMaxHeight

string \| number

| - | - | If setted, it defines the maximum height of the dropdown list | |

compact

boolean[]

| [false] | - | Optionally renders the label according to the value inside the array for each breakpoint |

Filters

A component that can be used for generating filters in the form of json schema objects and saving sets of filters as "views". The filters created by this component can be used to filter a collection of objects using the

SchemaSieve

object.

View story source

Schema

The

Filters

component requires a

schema

property which should be a json schema that defines the shape of the objects you want to filter. For example if you want to filter on a collection that looks like this:

[
  {
    name: 'Bulbasaur',
    caught: true,
  },
  {
    name: 'Pikachu',
    caught: true,
  },
  {
    name: 'Dratini',
    caught: false,
  }
]

You would define a schema that looks like this:

{
  type: 'object',
  properties: {
    name: {
      title: 'Name',
      type: 'string'
    },
    caught: {
      title: 'Has been caught',
      type: 'boolean'
    }
  }
}

If you provide a

title

property, it will be used to label the field when filtering, otherwise the field name will be used.

Views

Views represent a set of filters, along with an id and a name. This is a useful feature for storing a set filters and loading it again at a later point. A view can optionally have a

scope

property, which will correspond to the

slug

of a view scope, if you have provided one in the

Filters

property

viewScopes

property. Scopes allow you to easily add an extra layer of granularity/grouping to views that are generated. If you provide view scopes, the user can select a scope when creating a new view.

A view scope has the following properties:

| Name | Type | Description | | ------------- | --------- | ---------------------------------------------------- | | slug |

string

| A unique identifier for the scope | | name |

string

| A descriptive name for the scope | | label |

string

| An optional label to use for this scope when creating a view |

A view has the following properties:

| Name | Type | Description | | ------------- | --------- | ---------------------------------------------------- | | id |

string

| A unique identifier for the view | | name |

string

| A descriptive name for the view | | filters |

string

null

if now scopes are provided |

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

schema

object

| - | ✓ | A json schema describing the shape of the objects you want to filter | |

disabled

boolean

| - | - | If true, disable the entire

Filters

interface |

filters

object[]

| - | - | An array of json schemas to be displayed as the currently selected filters, typically used when loading when loading filters from storage | |

views

object[]

| - | - | An array of views, as described above, typically used when loading when loading views from storage | |

viewScopes

object[]

| - | - | An array of view scopes, as described above | |

onFiltersUpdate

(filters: object[]) => void

| - | - | A function that is called when filters are updated | |

onViewsUpdate

(views: object[]) => void

| - | - | A function that is called when views are updated | |

addFilterButtonProps

object

| - | - | Properties that are passed to the "Add filter" button, these are the same props used for the

Button

component | |

viewsMenuButtonProps

object

| - | - | Properties that are passed to the "Views" button, these are the same props used for the

DropDownButton

component | |

renderMode

Filters

interface are displayed. One of

all

add

search

views

summary

, or an array containing any of these values | |

dark

boolean

| - | - | If true, Set the

Filters

component against a dark background | |

compact

boolean[]

| - | - | Accept a boolean for each rendition breakpoint. If true remove

Filters

labels |

Fixed

Displays an element with a

fixed

position.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

top

right

bottom

left

ResponsiveStyle

| - | - | Sets the z-index of the component |

Flex

Displays an element using flexbox.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

alignItems

align-items

, if the value is an array, sets a responsive style corresponding to the theme's breakpoints |

justifyContent

justify-content

, if the value is an array, sets a responsive style corresponding to the theme's breakpoints |

flexDirection

flex-direction

, if the value is an array, sets a responsive style corresponding to the theme's breakpoints |

flexWrap

flex-wrap

css property

Form

A component that can be used for generating a form from a json schema object. The standard json schema types are supported, as well as the

date-time

format.

Under the hood, this component uses

react-jsonschema-form

and support all

uiSchema

options from that project.

Additional formats are supported, but require supporting widgets to be loaded. For example if you would like to support the mermaid format, you'll need to import the widget using

import 'renditon/dist/extra/Form/mermaid'

This import only needs to happen once, so it is recommended that its done at the root level of your application.

Custom uiSchema properties

Some templates and widgets support additional uiSchema options, defined using

ui:options

object in the

uiSchema

definition. Those are:

PasswordWidget

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

showPasswordStrengthMeter

boolean

| false | - | A boolean denoting whether a password strenth meter will be shown.

zxcvbn

should be loaded beforehand and set to the window object as

window.zxcvbn

ObjectField

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

responsive

boolean

| false | - | A boolean denoting whether the object fields should be wrapped in a row-directed flex container and wrap once their size is larger than the minimum| |

flex

Array

| - | - | Works together with

responsive

. It passes the

flex

value to the same-indexed field in the object. This allows you to have more control over the layout of the fields |

Captcha

If you wish to use a captcha (google recaptcha v2) in your form, you need to load the

captcha

widget using

import { CaptchaWidget } from 'renditon/dist/extra/Form/captcha'

and register it using

registerWidget

. View story source.

In order for the captcha to work, you also need to set a valid recaptcha API key to the

window.RECAPTCHA_V2_API_KEY

variable. A gotcha with the captcha widget is, upon submitting, you need to reset the captcha form value where you manage its state. Google only allows a captcha value (generated by clicking the captcha widget) to be verified only once against their API, after which it will be invalid so it needs to be reset.

API

registerWidget(format, widget)

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

schema

object

| - | ✓ | A json schema describing the shape of the data you would like to gather | |

submitButtonText

hideSubmitButton

boolean

| - | - | If true, do not display the form submit button | |

submitButtonProps

object

| - | - | Properties that are passed to the submit button, these are the same props used for the

Button

component | |

secondaryButtonProps

object

| - | - | If passed, it will show a secondary button, these are the same props used for the

Button

component | |

value

| - | - | The data that should be displayed in the form | |

onFormChange

(result: object) => void

| - | - | A function that is called when form data changes | |

onFormSubmit

(result: object) => void

| - | - | A function that is called when the form is submitted | |

uiSchema

object

| - | - | A configuration object used to change the styling and layout of the form. See the

react-jsonschema-form

docs for more details |

Heading

A component that displays a heading. By default an

tag is used. The exact heading type can be specifed by appending the element name to the component, for example

etc.

View story source

HighlightedName

By default, the background color of a

HighlightedName

component is generated automatically from its

children

(which must be a string), though this can be overridden.

View story source

Props

| Name | Type | Default | Required | Description | |------------|----------|-------------------------------------|----------|-----------------------------------------------------| |

children

string

| - | ✓ | The text to display inside the highlighted name | |

bg

string

| autogenerated from

children

| - | If passed, it will be used as the background color of the component | |

color

string

theme.colors.text.main

white

| - | If passed, it will be used as the text color of the component |

Img

Displays an image.

View story source

Inheritance

The attributes of an

element are also available.

Input

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

emphasized

boolean

| - | - | If true, use a larger size | |

monospace

boolean

| - | - | If true, render text in a monospace font | |

onChange

(e: Event) => void

| - | - | A function that is called when the input value changes |

Inheritance

The attributes of an

element are also available.

Link

Displays an anchor link.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

blank

boolean

| - | - | If true, open the link in a new tab | |

disabled

boolean

| - | - | If true, disable the link |

Inheritance

The attributes of an

element are also available.

List

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

children

ReactNode

| - | - | Each child represents a list item | |

ordered

boolean

| - | - | If true, render an ordered (numbered) list, otherwise render a bullet list |

Map

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

apiKey

string

| - | ✓ | Google maps API key | |

data

any[]

| - | ✓ | Passes the data that you wish to be used as a basis for rendering the map pins | |

dataMap

object

| - | ✓ | A mapping object between your data and location-specific fields (like latitude) | |

getIcon

(entry: any) => string

| - | - | Function that returns an icon based on the data entry | |

onItemClick

(entry: any) => void

| - | - | Callback function when an item on the map was clicked | |

mapClick

(e: google.maps.MouseEvent) => void

| - | - | Event triggered on map click that includes the clicked location's longitude and latitude |

Modal

Displays a centrally position modal overlay. Children passed to this component are rendered inside the modal.

View story source

Props

| Name | Type | Default | Required | Description | | --------------|-----------|-----------|------------|----------------------------------------------------- | |

title

string

| - | - | A title to display at the top of the Modal, only displayed if the

titleElement

property is not used | |

titleElement

titleDetails

title

, only displayed if the

titleElement

property is not used and a

title

property is provided | |

action

cancel

() => any

| - | - | A function that is called if the modal is dismissed | |

done

() => any

| - | ✓ | A function that is called if the primary modal button is clicked | |

primaryButtonProps

object

| - | - | Properties that are passed to the primary button, these are the same props used for the

Button

component | |

secondaryButtonProps

object

| - | - | If provided, will cause a secondary button to appear on the modal. These properties that are passed to that button, these are the same props used for the

Button

component | |

cancelButtonProps

object

| - | - | Properties that are passed to the cancel button, these are the same props used for the

Button

component | | style |

object

| - | - | Apply custom styles to Modal, the object is applied as a

style

attribute | | position | 'center' | 'top' | - | - | Start the modal from the center (default) or top |

Navbar

A component used to render a navigation bar.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

brand

JSX.Element

| - | ✓ | A JSX element used as the main branding in the navbar |

Notifications

To use this component, you first need to add the

NotificationsContainer

component at the root of your React application. You can then programatically add or remove notifications using the

notifications

module. For example:

import {notifications} from 'rendition';

const notificationId = notifications.addNotification("Hi there");
notifications.removeNotification(notificationId);

View story source

Props

The

NotificationsContainer

component doesn't take any props. You do all customizations on a per-notification basis. The

addNotification

function can take either a valid React node component, or the following options:

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

content

React.ReactNode

| - | ✓ | The content you wish to display in the notification | |

duration

number

| 6000 | - | The duration this notification will be shown for in

ms

means it will never close automatically | |

container

string

top-right

| - | The position of the notifications in the parent container.
One of

'top-left'   | 'top-right'   | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'

| |

type

string

| - | - | Optionally used to specify the intent of the notification.
One of

'danger' | 'warning' | 'success' | 'info'

. | |

id

number

onDismiss

() => void

| | - | A callback function that is triggered when the "dismiss" button is clicked |

Pager

Displays a pager widget.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

totalItems

number

| - | - | The total number of items to split into pages | |

itemsPerPage

number

| - | - | The number of items on each page | |

page

number

| - | - | The current page (zero-indexed) | |

nextPage

() => void

| - | - | Callback invoked when the "next page" button is clicked |

prevPage

() => void

| - | - | Callback invoked when the "previous page" button is clicked

ProgressBar

Displays a progress bar using a value representing a percentage.

View story source

Props

| Name | Type | Default | Required | Description | | --------------|-----------|-----------|------------|-------------------------------------------------------------- | |

primary

boolean

true

| - | If true, use the

primary

theme color | |

secondary

boolean

| - | - | If true, use the

secondary

theme color | |

tertiary

boolean

| - | - | If true, use the

tertiary

theme color | |

quarternary

boolean

| - | - | If true, use the

quarternary

theme color | |

danger

boolean

| - | - | If true, use the

danger

theme color | |

warning

boolean

| - | - | If true, use the

warning

theme color | |

success

boolean

| - | - | If true, use the

success

theme color | |

info

boolean

| - | - | If true, use the

info

theme color | |

emphasized

boolean

| - | - | If true, use a larger size | |

value

number

| - | ✓ | A value between 1 and 100 that represents the progress | | background |

string

| - | - | A CSS color string to use for the progress bar | | color |

string

| - | - | A CSS color string to use for the content of the progress bar |

RadioButton

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

checked

boolean

| - | - | If true, render the radio button as checked | |

disabled

boolean

| - | - | If true, set the radio button as disabled | |

label

string

| - | - | The label to render next to the radio button | |

onChange

(event: Event) => void

| - | - | Function called when the value of the radio button changes |

RadioButtonGroup

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

value

string

| - | - | Currently selected option value | |

options

["string"] | [{"disabled": boolean, "id": string, "label": string, "name": string, "value": string}]

| - | - | Settings for each radio button | |

onChange

(event: Event) => void

| - | - | Function called when the value of the radio button changes |

Search

Displays an input styled as a search bar.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

dark

boolean

| - | - | If true, uses a light colorscheme for use on a dark background | |

disabled

boolean

| - | - | If true, disable the input | |

placeholder

string

| - | - | A placeholder to use in the input | |

value

string

| - | ✓ | The value of the input | |

onChange

(event: Event) => void

| - | ✓ | A function that is called when the input changes |

Select

View story source

Props

You can refer to the grommet select page for all possible props.

Excluded props are:

'size' | 'selected' | 'focusIndicator' | 'margin'

Additional props are:

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

emphasized

boolean

| - | - | If true, use a larger size | |

invalid

boolean

| - | - | If true, adds red borders around the select |

Spinner

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

children

React.ReactNode

| | - | If the spinner has children, it will show an opaque overlay over the children when it is spinning | |

show

boolean

emphasized

boolean

label

string

React.ReactNode

| | - | A label that will be rendered next to the spinner. Renders on right-hand side for standard spinner, and below spinner for emphasized |

Steps

A visual guide showing a number of steps to be performed by the user. The

Steps

component takes one or more

Step

components as children.

If the

ordered

prop is

true

, the steps will be considered as an ordered (numbered) list. In this case, the

activeStepIndex

must be set and the

onClick

callback prop of the child

Step

components used to update the

activeStepIndex

View story source

Props

| Name | Type | Default | Required | Description | | ------------- | ------------- | --------- | ---------- | ----------- | |

children

Array

| - | - | The step components that form this sequence of steps | |

titleText

string

| - | - | If passed, the steps will have a title at the beginning | |

titleIcon

ReactNode

| - | - | If passed, an icon will be shown next to the title text, or on its own if there is no title text passed | |

onClose

() => void

| - | - | Function that is called when a user clicks on the close button, if not passed, no close button will be rendered | |

bordered

boolean

true

| - | If true (default), the steps container will have a visible border | |

ordered

boolean

false

| - | If true, the steps will be treated as an ordered list. Instead of the check icon, pending ordered steps will be displayed with a grey step number and active ordered steps with a blue step number. |

activeStepIndex

number

| - | - | If passed, specifies the step that is currently active. Only use with the

ordered

prop |

Step Props

| Name | Type | Default | Required | Description | | ---------- | ---------------------------------- | ------- | ---------- | ----------- | |

children

string

| - | ✓ | The text of the step | |

status

'pending' | 'completed' | 'none'

| - | ✓ | Whether the step has been completed or is still pending | |

onClick

| () => void | - | - | If passed, the step will be clickable. Note: If the steps are ordered, this callback should be used to update the
activeStepIndex
prop passed to the
Steps
component. |

Table

A component used to generate a styled table.

View story source

Columns

The

columns

property defines what columns the table should display, how they are rendered and whether or not the column is sortable.

The

columns

property should be an array of objects with the following properties:

| Name | Type | Required | Description | | ------------- | --------- | -------- | ---------------------------------------------------- | | field |

keyof T

| ✓ | The name of the field this column should render, this should correspond to a key on the objects passed to the

data

property of the

Table

component | | key |

string

field

provided and the row data (

field

field

provided and the row data (

Notes

For performance reasons table rows are only re-rendered if the row properties have changed. For this reason, rows will not re-render if their properties are mutated: you should clone the item instead, for example:

update (index) {
  const newData = this.state.data
  const element = newData[index]
  newData[index] = Object.assign({}, element, { active: !element.active })
  this.setState({ data: newData })
}

See the Updating data in a table story for an example of how this can be done using a high order component.

Additionally, because of this rendering behaviour the

render()

functions in the

Table

component's

columns

property should only use values provided to the render function. When

render()

functions are provided, they must act like pure functions with respect to their props. They should only rely on their arguments to generate their output and not use any context variables. If you are using a context variable in your

render()

function, then changes to that variable will not cause a re-render of the component and will not be reflected on the table.

Props

| Name | Type | Default | Required | Description | | ------------- | --------- | --------- | ---------- | ---------------------------------------------------- | |

columns

object[]

| - | ✓ | An array of column objects, as described above | |

data

T[]

| - | ✓ | An array of objects that will be displayed in the table | |

getRowHref

(row: T) => string

| - | - | If provided, each row in the table will be a clickable link, this function is used to create the link href | |

onCheck

(checkedItems: T[]) => string

| - | - | If provided, each row will begin with a checkbox. This function is called with every checked row every time a checkbox is toggled on or off. This property requires that you have provided a

rowKey

property | |

onRowClick

(row: T, event: Event) => void

| - | - | A function that is called when a row is clicked. This property requires that you have provided a

rowKey

property | |

onSort

(sort: TableSortOptions) => void

| - | - | A function that is called when a column is sorted | |

onPageChange

(page: number) => void

| - | - | A function that is called when the page is incremented, decremented and reset | |

sort

TableSortOptions

| - | - | sort options to be used both as a default sort, and on subsequent renders if the passed sort changes | |

rowAnchorAttributes

object

| - | - | Attributes to pass to the anchor element used in a row | |

rowCheckboxAttributes

object

| - | - | Attributes to pass to the checkbox element used in a row | |

rowKey

key of T

| - | - | A field on a row that contains a unique identifier, can help speed up render performance and is required for the

onCheck

property | |

toBodyPrefix

highlightedRows

| &ast;[] | - | - | Highlights one or more rows. This property requires that you have provided a

rowKey

property: the row with a

rowKey

property that matches one of these values is highlighted. |

usePager

boolean

| - | - | If true, a pager will be used when displaying items. |

itemsPerPage

number

| - | The number of items to be shown per page. Only used if

usePager

is true. Defaults to

. |

pagerPosition

| 'top' | 'bottom' | 'both' |

top

| - | Sets wether the pager is displayed at the top of the table, the bottom of the table or in both positions. Only used if

usePager

is true. Defaults to

top

Programmatically selecting rows

The component has a

setRowSelection

method that can be accesssed via ref.

It will accept an array of rows

T[]

, or an empty array in order to clear the selection.

This method requires that you have provided a

rowKey

property.

Tabs

A component used to render tabbed children components.

View story source

Props

You can refer to the grommet tabs page for all possible props.

Additional props are:

| Name | Type | Default | Required | Description | | --------- | --------- | ------- | -------- | ------------------------------------------------------- | |

compact

boolean

| - | - | If true, render tabs on a single line. (for mobile use) |

Tag

Represents a name-value pair with an optional operator between.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

value

string

| - | - | The value part of the tag | |

operator

boolean

':'

| - | The operator that goes between the name and value of the tag | |

name

boolean

| - | - | The name part of the tag, if not provided, only the value will be shown | |

multiple

Array

| - | - | An array of name-value pairs, with an optional delimiter to be used between the previous and current tag entry | |

onClose

(e: MouseEvent) => void

| - | - | Callback method, that if passed, a "close" button will be added to the right-hand side of the tag| |

onClick

(e: MouseEvent) => void

| - | - | Callback method, that if passed, the tag will become clickable |

Terminal

An xterm emulator built on top of xterm.js.

View story source

API

The

Terminal

component exposes a simple api, typically accessed via a

ref

Here is a simple example that writes a number every second:

import * as React from 'react'
import { Terminal } from 'rendition'

export class Logger extends React.Component {
  constructor (props) {
    super(props)
this.count = 0
  }
  componentDidMount () {
    this.interval = setInterval(() => {
        this.term.writeln(++this.count)
      }
    }, 1000)
  }
  render () {
    return (
       (this.term = term)} 
      />
    )
  }
}

resize()

Resize the

Terminal

component to fill its container.

clear()

Clear all output from the terminal.

writeln(text)

Write text to the terminal, followed by a line break.

write(text)

Write text to the terminal.

destroy(text)

Tear down the terminal instance.

Remounting old instances

If you'd like to preserve a terminal session and remount it to the DOM at a later point, you will need to set the

persistent

property to

true

and then access the readonly property

tty

and store it in memory. The

persistent

flag prevents the

Terminal

component form destroying the

tty

instance when it unmounts. When you want to remount the session, instantiate a new

Terminal

component and provide the

tty

value as the

ttyInstance

property. When a

ttyInstance

property is provided, the

Terminal

component will use that instance instead of creating a new one.

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

ttyInstance

object

| - | - | An existing

Terminal.tty

instance to use instead of creating a new one | |

persistent

boolean

| - | - | If true, don't destroy the

Terminal.tty

instance when the component unmounts | |

nonInteractive

boolean

| - | - | If true, the component will go into a "read-only" state, useful for displaying logs | |

color

string

| - | - | A CSS color string that sets the background color of the terminal | |

config

object

| - | - | Startup options to pass to the tty instance, see the xterm.js options for more detail |

TextWithCopy

Displays text that can be copied to the clipboard.

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

copy

string

| - | ✓ | The value that should be copied to the clipboard |

showCopyButton

Textarea

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

monospace

boolean

false

| - | If true, render text in a monospace font | |

autoRows

boolean

false

| - | If true, the textarea

rows

property will be changed automatically based on the content of the textarea, this behaviour will only work with a controlled input (i.e. you have used the

onChange

property | |

minRows

number

| - | - | Set the minimum number of rows | |

maxRows

number

| - | - | Set the maximum number of rows | |

onChange

(e: Event) => void

| - | - | A function that is called when the textarea value changes |

Inheritance

The attributes of a

element are also available.

Tooltips

Tooltips are somewhat special in how they are used. Instead of using them as a typical React component, they can be added to a supported component using the

tooltip

attribute. For example, to add a tooltip to a

Button

component you would do the following:

  Click me

If the

tooltip

attribute is a string then a tooltip containing the strings content will be displayed above the component.

If you need more control over the tooltip, you can set the attribute to an object with the following properties:

| Name | Type | Required | Description | | ------------- | --------- | -------- | ---------------------------------------------------- | | text |

string

'hover'

'top'

| | containerStyle |

object

| - | Apply custom styles to the tooltip outer container, the object is applied as a

style

attribute | | innerStyle |

object

| - | Apply custom styles to the tooltip inner container, the object is applied as a

style

attribute | | arrowStyle |

object

| - | Apply custom styles to the tooltip arrow, the object is applied as a

style

attribute |

The following rendition components support the

tooltip

attribute:

```
Alert
```
```
Badge
```
```
Box
```
```
Button
```
```
CodeWithCopy
```
```
DropDownButton
```
```
Fixed
```
```
Flex
```
```
Heading
```
```
Txt
```
```
Link
```

View story source

Txt

Displays a text block. A

tag can be used with

and a

tag can be used with

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

monospace

boolean

| - | - | If true, render text in a monospace font | |

bold

boolean

| - | - | If true, render text in a bold font | |

italic

boolean

| - | - | If true, render text in an italic font style | |

caps

boolean

| - | - | If true, render text in uppercase | |

align

string

| - | - | Align text inside the component, one of 'left', 'right', 'center', 'justify', 'justify-all', 'start', 'end', 'match-parent', 'inherit', 'initial', 'unset' | |

whitespace

string

| - | - | Equivalent to the CSS

white-space

property, one of 'normal', 'nowrap', 'pre', 'pre-line', 'pre-wrap', 'initial', 'inherit' |

JsonSchemaRenderer

A component used to render JSON data based on a schema and a UI schema.

View story source

Props

| Name | Type | Default | Required | Description | | -----------|----------|---------|----------|-------------- | |

value

| - | - | The data that should be rendered | |

schema

object

| - | ✓ | A json schema describing the shape of the data you would like to render | |

uiSchema

object

| - | - | A configuration object used to change the styling and layout of the rendered data.| |

extraFormats

[Format]

| - | - | An optional array of formats to pass to the validator, and an optional custom widget for the format. See addFormat for details of formatters. | |

extraContext

object

| - | - | Extra context used by

json-e

when transforming the UI schema. | |

validate

boolean

| - | - | If set, the

value

will be validated against the

schema

and any error will be displayed at the top of the rendered output. Useful for debugging. |

Markdown

A simple component for rendering GitHub flavored markdown. This component sanitizes input. This component is not loaded by default as it relies on a markdown parsing package that you may not want to include in your application. You can load this component using:

import { Markdown } from 'rendition/dist/extra/Markdown';

If you need to customize the conversion of markdown to HTML you can supply the

sanitizerOptions

prop. In this case, use the defaults as a starting point for your options:

import { Markdown, defaultSanitizerOptions } from 'rendition/dist/extra/Markdown';

Generated html inherits styles from rendition components. i.e an anchor will be rendered as a

Link

component.

Html inside the markdown is sanitized and stripped of any inline js and css. so they will always be rendered.

Components can be overridden by using

componentOverrides

prop.

View story source

Props

| Name | Type | Default | Required | Description | | ---------------------- | -------------------------------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | |

children

string

| - | ✓ | The markdown source that should be rendered | |

sanitizerOptions

Object

| | - | Specifies the options used when sanitizing the generated HTML. Passing

null

would disable the sanitization. | |

componentOverrides

Object

| - | - | Object specifying component Overrides. ex.

{ p: Txt.p }

| |

decorators

Object

| - | - | Decorate part of the text if it matches some condition | |

disableRawHtml

boolean

disableCodeHighlight

boolean

| false | - | when disabled code blocks will not highlight syntax |

Any other properties supplied are spread to the root element (

Txt

Inheritance

The properties of the

Txt

component are also available.

MarkdownEditor

A markdown editor based on simple MDE editor

import { MarkdownEditor } from 'rendition/dist/extra/MarkdownEditor';

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

value

string

| - | ✓ | The markdown-flavored text | |

onChange

(text: string) => void

| - | ✓ | Callback called on every content change |

Mermaid

Generate charts from text using mermaidjs. This component is not loaded by default as it relies on the mermaidjs library that you may not want to include in your application. You can load this component using:

import { Mermaid } from 'rendition/dist/extra/Mermaid';

View story source

Props

| Name | Type | Default | Required | Description | | ------ | ------ | --------- | ---------- | ------------- | |

value

string

| - | ✓ | The mermaid source that should be rendered |

Provider

Wrap your application in the

component so that child components can correctly inherit the default theme. You can optionally provide your own theme.

Accessing the theme object

You can access the theme object in

's descendant components using the

useTheme

hook:

import React from 'react'
import { useTheme } from 'rendition';

const MyComponent = () => {
  const theme = useTheme()
  // ...
}

Styled system

All components support styled-system attributes, allowing you to use a shorthand properties for styling components. The properties can have the properties in the form of

string | number | Array

. If an array is provided, then a property is chosen based on the width of the screen. The screen width corresponds to a breakpoint set in the

theme

property of the

Provider

component, by default this is set to

[32, 48, 64, 80]

where each number is the screen width in ems.

| Name | Type | Description | | --------------|-------------------|--------------------------------------------- | | width |

ResponsiveStyle

| sets the width | minWidth |

ResponsiveStyle

| sets the min-width | maxWidth |

ResponsiveStyle

| sets the max-width | height |

ResponsiveStyle

| sets the height | minHeight |

ResponsiveStyle

| sets the min-height | maxHeight |

ResponsiveStyle

| sets the max-height | fontSize |

ResponsiveStyle

| sets the font size | display |

ResponsiveStyle

| sets the

display

css property | color |

ResponsiveStyle

| sets the

color

css property | bg |

ResponsiveStyle

| sets the

background

css property | m |

ResponsiveStyle

| sets the

margin

css property | mt |

ResponsiveStyle

| sets the

margin-top

css property | mr |

ResponsiveStyle

| sets the

margin-right

css property | mb |

ResponsiveStyle

| sets the

margin-bottom

css property | ml |

ResponsiveStyle

| sets the

margin-bottom

css property | mx |

ResponsiveStyle

| sets both the

margin-right

and

margin-left

css properties | my |

ResponsiveStyle

| sets both the

margin-top

and

margin-bottom

css properties | p |

ResponsiveStyle

| sets the

padding

css property | pt |

ResponsiveStyle

| sets the

padding-top

css property | pr |

ResponsiveStyle

| sets the

padding-right

css property | pb |

ResponsiveStyle

| sets the

padding-bottom

css property | pl |

ResponsiveStyle

| sets the

padding-left

css property | px |

ResponsiveStyle

| sets both the

padding-right

and

padding-left

css properties | py |

ResponsiveStyle

| sets both the

padding-top

and

padding-bottom

css properties

&ast;

ResponsiveStyle

corresponds to a type of
string | number | Array

Extra components

Some components in the storybook are grouped separately under the

Extra

label. These components are not loaded by default as they rely on other large packages that you may not want to include in your application. If you would like to use them they can be loaded using by prefixing the component name with

rendition/dist/extra/

. For example to load the

Markdown

components you can use:

import { Markdown } from 'rendition/dist/extra/Markdown';

Unstable/Beta components

Some components in the storybook are grouped seperately under the

Beta

label. These components are experimental and still under development, as such their API may change without notice. They should not be used in a production application. If you would like to try them out they can be loaded using

import * from 'rendition/dist/unstable'

Upgrading

Upgrading from 3.x to 4.x

Upgrading from 4.x to 5.x

Upgrading from 6.x to 7.x

Contributing

Please read our contribution guidelines

rendition

by balena-io-modules

No Items, yet!

Rendition

Table of Contents

Installation

Usage

Components

Accordion

Props

Alert

Props

ArcSlider

Props

Inheritance

Avatar

Props

Badge

Props

Banner

Props

Box

Props

Button

Props

ButtonGroup

Card

Props

Checkbox

Props

Container

Copy

Props

Divider

Props

DropDownButton

Props

Filters

Schema

Views

Props

Fixed

Props

Flex

Props

Form

Custom uiSchema properties

PasswordWidget

ObjectField

Captcha

API

registerWidget(format, widget)

Props

Heading

HighlightedName

Props

Img

Inheritance

Input

Props

Inheritance

Link

Props

Inheritance

List

Props

Map

Props

Modal

Props

Navbar

Props

Notifications

Props

Pager

Props

ProgressBar

Props

RadioButton

Props