Alerts

npm install pui-react-alerts --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
closeLabel no Node 'Close alert' Screen reader label attached to close button
dismissable no Boolean false If true, render a close button
onDismiss no Function Callback that is called when the user clicks the close button
show no Boolean If set, overrides the close button. True shows the alert, false hides the alert.
withIcon no Boolean false If true, render alert with an icon

Basic usage

Alerts use the Iconography component when using withIcon or dismissable. If you use those props, you will need to add an svg loader:

Import the subcomponents:

import {SuccessAlert, InfoAlert, WarningAlert, ErrorAlert} from 'pui-react-alerts';

Dismissable

Add the dismissable property to add a close button to the alert.

If you want a callback to be called when the close button is clicked, set the onDismiss property to that callback.

Alerts with Icons

If you want an icon to be displayed, set the withIcon property.

Here's a dismissable alert with an icon

Autocomplete

npm install pui-react-autocomplete --save

Props

Property Required Type Default Description
className no String className to add to autocomplete
disabled no Boolean whether the input is disabled
input no Object autocompleteinput overrides the input for autocomplete
maxItems no Number 50 the maximum number of items in the autocomplete list
onClick no Function onClick to add to the input
onFilter no Function lets you apply an additional filter to the autocomplete list
onFocus no Function onFocus to add to the input
onInitializeItems no Function done => done([]) returns the values to initially populate the autocomplete list
onPick no Function callback when something is picked from the list
onSearch no Function To override the default search algorithm, pass your custom function to the autocomplete as the prop onSearch.
placeholder no String 'search' placeholder text for the input
trieOptions no Object Options for the default TrieSearch algorithm (e.g. ignoreCase: a boolean is set to true by default, splitOnRegEx: a RegEx)
value no String used when the input is a controlled input

Basic usage

import {Autocomplete} from 'pui-react-autocomplete';

onInitializeItems

The callback passed to this function should return the values to initially populate the list of items.

It's designed to be able to be used asynchronously:

const onInitializeItems = callback => {
  $.get('example.com/autocomplete_items').then(items => callback(items));
};

But it can also just be used synchronously:

const onInitializeItems = callback => callback(['foo', 'food', 'bar']);

onPick

By default, when a user selects a list item, nothing happens except hiding the list.

const onPick = value => {
  $.post('example.com/add_to_cart?thing=' + value);
};

onSearch

To override the default search algorithm, pass your custom function to the Autocomplete as the prop onSearch.

onSearch is given the current value of the input and a callback.

The callback should return the items that should be shown in the list given that input value.

The list should be an array of objects with the value key e.g. [{value: 'foo'}, {value: 'food'}, {value: 'foe'}]

It's designed to be able to be used asynchronously:

const onSearch = (value, callback) => {
  $.get('example.com/autocomplete_results?value=' + value).then(results => callback(results));
};

But it can also just be used synchronously:

const onSearch = (value, callback) => {
  callback(myCustomList.filter(entry => entry.includes('foo-' + value + '-bar'));
};

Back to Top

npm install pui-react-back-to-top --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
alwaysVisible no Boolen false If alwaysVisible is not set, the component will only appear after the window has been scrolled.

Basic usage

(The extra loaders are for the Iconography component.)

Import the subcomponent:

import {BackToTop} from 'pui-react-back-to-top';

You can use this component to scroll to the top of a page.

The button will be fixed to the bottom right hand corner of the page.

You can place the link anywhere in your markup, but best practices are either towards the top or bottom of your markup.

Buttons

npm install pui-react-buttons --save

Props

Property Required Type Default Description
alt no Boolean false Whether to render as 'alternate' button
flat no Boolean false Whether to render as a 'flat' button
href no String If specified, button clicks will redirect to this href
iconOnly no Boolean false If specified, will render as an icon button
large no Boolean false Whether to render the button large
small no Boolean false Whether to render the button small

Basic usage

Import the subcomponents:

import {DefaultButton, PrimaryButton, DangerButton, BrandButton} from 'pui-react-buttons';
import {Icon} from 'pui-react-iconography';

Buttons use the button tag by default. If you'd like a link rather than a button, simply add an href attribute. The aria-label attribute will be populated with the button text, unless an aria-label value is explicitly supplied.

Styling

Every button type has a default style, an alt style (with inverted colors and a transparent background) and a flat style (alt with transparent borders).

Button Button Alt Button Flat Description
This the default button style.
Use this button for primary actions.
This button is for delete actions, these actions should also have a confirmation dialog
This button is for marketing purposes only

The most common button examples are below:

Sizes

To make a button large, set the large property to true, to make it small, set small to true.

Icons

Buttons can contain icons.

They can also be icon buttons, by specifying iconOnly. Note that icon buttons are not supplied an aria-label value by default.

Collapse

npm install pui-react-collapse --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
divider no Boolean Specifying this property adds a divider between the clickable region and the expanded content region
header yes Node The text of the clickable region to toggle the expand/collapse states
defaultExpanded no Boolean false Setting this to true will make the component start expanded when the page loads

Basic usage

(The extra loaders are for the Iconography component.)

Import the subcomponents:

import {BaseCollapse, AltCollapse, Collapse} from 'pui-react-collapse';

Collapse components are implementations of the Accordion style. In all Collapse component variations, the header prop describes the text of the clickable region to toggle the expand/collapse states. You can pass defaultExpanded as a prop to the Collapse and it will start expanded when the page loads.

This is a basic collapse with no additional styles.

Alt

This is a basic collapse with an +/- icon in the clickable region.

Arrows

This is a basic collapse with an arrow icon in the clickable region.

Adding Dividers

To add a divider between the clickable region and the expanded content region, simply set the divider property to be true.

Copy To Clipboard

npm install pui-react-copy-to-clipboard --save

Props

Property Required Type Default Description
text yes String Text that is copied when the user clicks
onClick no Function () => () Click handler

Basic usage

CopyToClipboardButton uses the Iconography component. You will need to add an svg loader:

npm install babel-loader react-svg-loader --save-dev

Import the subcomponents:

import {CopyToClipboard, CopyToClipboardButton} from 'pui-react-copy-to-clipboard';

Below is a common example combining a readonly input and a copy button. Note that there is custom css on the styleguide to get the positioning right.

import {Input} from 'pui-react-inputs';

Dividers

npm install pui-react-dividers --save

Props

Property Required Type Default Description
inverse no Boolean Specifying this prop inverses the divider
size no oneOf('large') Changes the size of the component

Basic usage

Import the subcomponents:

import {Divider} from 'pui-react-dividers';

Dividers draw horizontal lines between different content groupings.

On a dark background, use these inverse dividers

Dropdowns

npm install pui-react-dropdowns --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
buttonAriaLabel no String aria-label for the button
buttonClassName no String Classname to add to the button
closeOnMenuClick no Boolean true If false, do not close the menu when clicking in the dropdown menu
disableScrim no Boolean false If true, do not close the menu when clicking outside the dropdown
flat no Boolean If true, dropdown toggle has no borders and is transparent
floatMenu no Boolean false If true, float the dropdown menu. This only applies to the basic dropdown
href no String Link for the default option (split dropdown only)
icon no String 'chevron_down' Name of the svg to use for the toggle icon
link no Boolean If true, color the dropdown toggle like a link
labelAriaLabel no String aria-label for the label (split dropdown only)
menuAlign no oneOf(['none', 'left', 'right']) 'none' Sets the alignment of the menu with the button
onClick no Function Callback that fires after clicking the button
onEntered no Function Callback that fires after opening the dropdown
onExited no Function Callback that fires after closing the dropdown
onSelect no Function Callback that fires after clicking the default option (split dropdown only)
scroll no Boolean false Enables scrolling in the dropdown menu when enabled
showIcon no Boolean true If false, do not render an icon in the dropdown toggle. Icon can not be hidden if split or leaving out title.
size no oneOf(['normal', 'large', 'small']) 'normal' Sets the size
split no Boolean If true, separates the button text from the toggle
title no Node The button contents

(The extra loaders are for the Iconography component.)

Import the subcomponents:

import {Dropdown, DropdownItem} from 'pui-react-dropdowns';

Basic Dropdown

This is the basic dropdown. It has an attached menu that extends from the bottom.

Basic Dropdown With Custom Icon

Float Dropdown Menu

The float dropdown menu is spaced 2px below the toggle. It can also be pinned to the left or right for content that exceeds the parent dropdown width.

Float Scroll Menu

Lists that are indeterminately long can utilize the float scroll menu. The size is fixed so you'll have to customize the fixed height to achieve your desired results.

Split Dropdown

Action with additional actions hidden in a dropdown. Floating menu only.

Flat Button Dropdown

Dropdown with the flat button styling. Floating menu only.

Dropdown with the link styling, retains dropdown padding. Floating menu only.

Icon Dropdown

Rendered when no title is specified. Floating menu only.

Sizing

Expander

npm install pui-react-expander --save

Props

Property Required Type Default Description
expanded no Boolean false Whether to render expanded or not
onEntered no Function Hook that fires when expand occurs
onExited no Function Hook that fires when collapse occurs

Note: all props of the 'collapse

Basic usage

Import the subcomponent:

import {ExpanderContent} from 'pui-react-expander';

Expanders are collapsible content areas. Unlike their accordion counterparts, Expanders do not require a parent collapse and child content structure. This means you can trigger the expanding and collapsing content from somewhere else within the DOM.

The Expander component accepts an "onEntered" and an "onExited" callback that triggers after animation is complete.

See the example below for how to use these components in your own application.

Forms

Checkbox

npm install pui-react-checkbox --save

Props

Property Required Type Default Description
displayError no Boolean false Displays the error message when true
errorMessage no Node Message that gets displayed when displayError is true
inputClassName no String Classname of the inner input element
id no String The inner label will specify htmlFor=id
label no Node The content of this label
labelClassName no String Sets the wrapping label classname

Basic usage

Import the subcomponent:

import {Checkbox} from 'pui-react-checkbox';

A Checkbox component renders a checkbox with a label. It accepts standard checkbox input properties (such as placeholder).

A Checkbox component display a custom errorMessage when the displayError parameter is truthy.

Inputs

npm install pui-react-inputs --save

Input uses the Iconography component for search and success. If you use those props, you will need to add an svg loader:

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
autoFocus no Boolean false Focus the inner input element on mount
displayError no Boolean false Displays the error message when true
errorMessage no Node Message that gets displayed when displayError is true
inputClassName no String Classname of the inner input element
id no String The inner label will specify htmlFor=id
label no Node The content of this label
labelClassName no String Sets the wrapping label classname
leftIcon no oneOf(String, Element) Inputs have a custom svg icon when leftIcon is provided
placeholder no String Input placeholder
search no Boolean false Inputs have a magnifying glass when the search prop is true
size no oneOf('small', 'medium', 'large') 'medium' Size variations
success no Boolean false Inputs display a checkmark when the success prop is true

Basic usage

Import the subcomponent:

import {Input} from 'pui-react-inputs';

Input components can be used on their own as inputs. They accept standard text input properties (such as placeholder).

Inputs will render a label if given label. If given id, clicking on the label will focus the input.

Inputs display a custom errorMessage when the displayError parameter is truthy.

Inputs display a checkmark when the success prop is true.

Inputs have a magnifying glass when the search prop is true

Inputs have a custom svg icon when leftIcon is provided. The custom icon will override the search prop if both are provided.

Input has a size attribute that takes three options: small, medium (default), and large.

To demonstrate how to use an Input in a more complex example, let's say we want to filter a list based on the user's input. We can accomplish this by creating a stateful component which is composed of the Input and the list to filter.

Radio

npm install pui-react-radio --save

Props

RadioGroup

Property Required Type Default Description
id no String The id of the element
name yes String This name is passed to all children, so you don't have to specify name manually each time
onChange no Function Callback that fires each time selection is changed

Radio

Property Required Type Default Description
defaultChecked no Boolean false Whether this element is default checked
value yes String Value of the radio element
onChange no Function Callback that fires when this element selection is changed
id no String The id of the element
className no String The classname of the element
style no Object Individual styling of the element
disabled no Boolean false Whether the radio is disabled

Basic usage

For the example, you also need to install Grids and require Col from it.

Import the subcomponents:

import {RadioGroup, Radio} from 'pui-react-radio';

Using React radio buttons in a form is fairly straightforward.

In this case, the name attached to RadioGroup will be applied to all of Radio children.

Additionally, special behaviors can be added to the onChange event handler exposed by radio groups. In this example, additional form controls are displayed when the user selects the third radio button.

Similar to the name property, the onChange handlers is passed down to all child components.

Toggle

npm install pui-react-toggle --save

Props

Property Required Type Default Description
id no String The id of the element
onChange no Function Callback that gets fired when toggle occurs
size no oneOf('small', 'medium', 'large') 'medium' Size variations

Basic usage

Import the subcomponent:

import {Toggle} from 'pui-react-toggle';

The Toggle component takes an onChange callback.

Toggles accept a checked prop that turns on the switch. Note that you must handle the addition and removal of the checked property yourself.

Toggle has a size attribute that takes three options: small, medium (default), and large.

Grids

npm install pui-react-grids --save

Props

Row properties:

Property Required Type Default Description
componentClass no Node div The component to render the row
gutter no oneOf('sm', 'md', 'lg') 'lg' Sets the size of the gutter

Col Properties

Property Required Type Default Description
componentClass no Node div The component to render the row
xs, sm, md, lg no Number Width of the column (out of 24) at the xs, sm, md, or lg screen width
xsHidden, smHidden, mdHidden, lgHidden no Boolean If true, hide the column at the relevant screen width
xsOffset, smOffset, mdOffset, lgOffset no Number Offset of the column (out of 24)
xsPush, smPush, mdPush, lgPush no Number Offset to change the order of grid columns to the right with
xsPull, smPull, mdPull, lgPull no Number Offset to change the order of grid columns to the left with

Basic usage

Import the subcomponents:

import {Row, Col} from 'pui-react-grids';

Examples

Example: Mobile and Desktop

Don't want your columns to simply stack in smaller devices? Use the extra small and medium device grid classes by adding .col-xs-* .col-md-* to your columns. See the example below for a better idea of how it all works.

Gutter Sizes

Flex Grids

npm install pui-react-flex-grids --save

Props

Grid properties:

Property Required Type Default Description
gutter no bool true Whether to include a gutter between columns or not

FlexCol Properties

There are none

Basic usage

Import the subcomponents:

import {Grid, FlexCol} from 'pui-react-flex-grids';

Examples

Iconography

This component is limited to projects that use Webpack. It requires the webpack loaders babel-loader and react-svg-loader.

npm install pui-react-iconography --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
src yes String Name of the svg to load
style no Object React Style Object
verticalAlign no oneOf('middle', 'baseline') 'middle' Alignment of icon

Basic usage

Import the subcomponent:

import {Icon} from 'pui-react-iconography';

Use the src attribute to load the appropriate icon. For a full list of available icons, go to http://pivotalicons.cfapps.io. You can also reference icons located in the app/svg folder at the root of your project (defined here as the location of your package.json). Create that directory and populate it with your custom svgs. Custom svgs must be suffixed ".svg," and they are referenced by the name of the svg (without the ".svg" suffix).

Icons by default will be sized based on the local font size. You can override the size of the icon by changing the font-size in the style prop:

Icons by default are vertically aligned 'middle'. This should align with most html elements except for text. Text in html has different alignment, so the default Icon alignment will look wrong. To align an Icon with text, set verticalAlign to 'baseline'

Spinner

Spinner behavior is determined by size. Note that the large spinner moves relatively slowly, whereas the small spinner moves more quickly and dramatically. In all cases, the base height and width is 1em and is meant to be overwritten with a font-size attribute. The font sizes provided here are meant as suggestions.

Images

npm install pui-react-images --save

Props

Property Required Type Default Description
responsive no Boolean false Whether this image should resize responsively
href no String If set, image becomes a link
alt no String Alt text
src yes String Image src

Basic usage

Import the subcomponent:

import {Image} from 'pui-react-images';

Images in React can be responsive and/or wrapped in a link.

Labels

npm install pui-react-labels --save

Props

Property Required Type Default Description
className no String 'label label-primary' Classname of the label

Basic usage

Import the subcomponents:

import {Label} from 'pui-react-labels';

Labels are a straightforward implementation of the Label style.

Labels can be used on their own:

Labels used within an element which already has font modifier styles will use the parents' styling. For example:

Lists

npm install pui-react-lists --save

Props

Property Required Type Default Description
className no String Classname of the list
unstyled no Boolean false Whether to style the list
divider no Boolean false Whether to include a divider between items

Breadcrumb

Import the subcomponents:

import {BreadcrumbList, ListItem} from 'pui-react-lists';

Inline

Import the subcomponents:

import {InlineList, ListItem} from 'pui-react-lists';

Ordered

Import the subcomponents:

import {OrderedList, ListItem} from 'pui-react-lists';

Unordered

Import the subcomponents:

import {UnorderedList, ListItem} from 'pui-react-lists';

Draggable

npm install pui-react-draggable-list --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
onDragEnd no Function Callback when a drag event has completed
innerClassName no String Use this to specify the classname of the inner div

Basic usage

(The extra loaders are for the Iconography component.)

Import the subcomponents:

import {DraggableList} from 'pui-react-draggable-list';
import {DraggableListItem} from 'pui-react-draggable-list';

Creates a draggable list.

The property onDragEnd is a callback when a drag event has completed. Use this if you need to make an API call to update the order of some elements.

Stream List

npm install pui-react-lists pui-react-stream-list pui-react-buttons --save

Props

Property Required Type Default Description
showNewItems yes Function Callback that fires when new items button is clicked
singularNewItemText no String Text to display when there is one new item
pluralNewItemsText no String Text to display when there are many new items
numNewItems yes Number Number of new items

Basic usage

Import the subcomponents:

import {StreamList, StreamListItem} from 'pui-react-stream-list';

// for the example
import {DefaultButton} from 'pui-react-buttons'

Use this component when you have streaming/polling data that you want to display in a list. As items roll in (polling, streams, websockets - your choice), add the items to the list. The user will see a "n new item(s)" button animate in at the top of the list. When the user clicks the button, the new items appear in the list.

Media

npm install pui-react-media --save

Props

Property Required Type Default Description
image yes Node The image displayed
innerClassName no String The classname of the inner element
mediaSpacing no oneOf('small', 'medium', 'large', 'xlarge') Amount of whitespace between media and body
stackSize no oneOf('xsmall', 'small', 'medium', 'large') At what breakpoint should the media object stack
vAlign no oneOf('middle', 'bottom') Vertical alignment of the body (used for large images with small content next to it, usually centered)
placement no oneOf('left', 'right') 'left' Horizontal placement of the media
className no String The classname of the element

Basic usage

Import the subcomponents:

import {Media, Flag} from 'pui-react-media';

// for the example
import {Image} from 'pui-react-images';

A Flag is a special type of media that is vAlign='middle'.

The images or other media can be aligned top, middle, or bottom. The default is top aligned.

The base button renderer. You won't really interact with this directly.

Vertical Alignment

Spacing

Media spacing can be added to the left and right medias. If no spacing is defined, it defaults to large.

Modals

npm install pui-react-modals --save

Props

Property Required Type Default Description
acquireFocus no Boolean true Acquire focus just before modal onEntered
animation no Boolean true Opens and closes the modal widow with sliding and fading animations.
dialogClassName no String A CSS class to apply to the modal dialog
keyboard no Boolean true Set to false to prevent escape from closing the modal dialog
onEntered no Function Callback that fires after the modal has finished animating in
onExited no Function Callback that fires after the modal has finished animating out
onHide no Function () => () Callback that fires as soon as the modal begins closing
show no Boolean Whether the modal should be opened or closed
size no String Size variations
title no Node Title of the modal, shown at the top of the modal

Basic usage

Import the subcomponents:

import {BaseModal, ModalBody, ModalFooter} from 'pui-react-modals';

// for the example
import {DefaultButton} from 'pui-react-buttons';

We provide 3 components that can be used to assemble modals:

  • BaseModal
  • ModalBody
  • ModalFooter

Note: A modal will be rendered at the end of body instead of the DOM node it is given. This makes positioning work regardless of where you render the modal. One side effect is ReactDOM.findDOMNodedoes not actually find the modal DOM node.

Notifications

npm install pui-react-notifications --save

npm install babel-loader react-svg-loader --save-dev

(The extra loaders are for the Iconography component.)

Props

Property Required Type Default Description
size no oneOf('h1', 'h2', 'h3', 'h4', 'h5', 'h6') Size of the notification

Basic usage

Import the subcomponents:

import {Notifications, AlertNotifications, NotificationItem, AlertNotifications} from 'pui-react-notifications';

// for the example
import {Flag} from 'pui-react-media';
import {Label} from 'pui-react-labels';
import {Icon} from 'pui-react-iconography';

Here's an example if there are no notifications:

Here's an example if there are notifications:

Notification Sizing

Alerts

Here's an example if there are no alerts:

Here's an example if there are alerts:

If you want to customize the notification dropdown, you can use className to add a modifier class to the btn-group. id and style will be applied to the notfication button.

Pagination

npm install pui-react-pagination --save

Props

Property Required Type Default Description
items no Number 1 The number of page links displayed
next no Boolean true Option to display a 'next page' button
prev no Boolean true Option to display a 'previous page' button
activePage no Function Option to make a link styled as 'active'
onSelect no Function Callback that is called on click of a link

Basic usage

Import the subcomponents:

import {Pagination} from 'pui-react-pagination';

The Pagination component provides a styled list of links used to navigate through a paginated list. By default, the component includes a 'previous page' button, a 'next page' button, and one link.

The following is an example of pagination with extra props:

Panes

npm install pui-react-panes --save

Props

Property Required Type Default Description
className no String Classname of the element
innerClassName no String Classname of the inner element

Basic usage

Import the subcomponents:

import {Pane, BasePane} from 'pui-react-panes';

The Pane component is a straightforward implementation of the Pane styling. Any className values passed through are passed to the underlying .pane.

In the event that you need additional configuration applied to a Pane, you can use the BasePane component which accepts properties for className and innerClassName.

These values are added to the class name of the .pane and the .container respectively.

Panels

npm install pui-react-panels --save

Props

Property Required Type Default Description
header no Node Node to render in the header
footer no Node Node to render in the footer
actions no Node Node to render as actions in the header (recommended: array of nodes)
subtitle no Node An element or text to render as the subtitle in the header (only works if header is a string)
innerClassName no String The className to be added on the panel body
padding no String Padding to use on the panel body (e.g pam, pan, phl, ptl)
scrollable no oneOf(Boolean, Number) Use default scrolling height when boolean or a specified scrolling height

Basic usage

Import the subcomponents:

import {Panel} from 'pui-react-panels';

Panel components are straightforward implementations of the Panel styling. The Panel component itself is the base, and there are a few different properties that can be applied to achieve the desired result.

A ScrollingPanel is created by using a Panel component and including a true value for the scrollable property. Alternatively, if this value is a number, it will become the height of the scrollable panel in pixels.

See examples below.

Portals

npm install pui-react-portals --save

Props

PortalSource/PortalDestination

Property Required Type Default Description
name yes String Use same name to connect sources and destinations

Basic usage

Import the subcomponents:

import {PortalSource, PortalDestination} from 'pui-react-portals';

The Portal components render DOM nodes elsewhere on the page. This is useful for things like modals, tooltips, and dropdowns, when you want to define the content near the trigger, but have it display at the bottom of the page (generally to solve z-index and overflow incompatibilities).

For example, modals can be rendered at the bottom of <body>, but the React component that creates the modal content (e.g. a <button>) does not have access to <body> directly. If a PortalDestination is put at the bottom of <body>, a PortalSource can then be used anywhere without knowing about <body>.

Select

npm install pui-react-select --save

npm install babel-loader react-svg-loader --save-dev

(The extra loaders are for the Iconography component.)

Props

Property Required Type Default Description
defaultValue no Any The initial value for the select when the select is uncontrolled
name no String The name of the hidden input, useful when used in a form
onChange no Function Callback that fires when the select is changed, must be provided for controlled inputs
onEntered no Function Callback that fires after opening the select
onExited no Function Callback that fires after closing the select
options yes Array Options for the select, can be string or numbers or an object with label and value (e.g. ['one', 'two', 'three'], [1, 2, 3], [{label: 'yes', value: 1}, {label: 'no', value: 0}])
value no Any The value for the select when it is controlled, must be used with an onChange function to update the value of the select

Basic usage

Import the subcomponents:

import {Select} from 'pui-react-select';

This is the basic select:

Svg

This component is limited to projects that use Webpack. It requires the webpack loaders babel-loader and react-svg-loader. If you are using pui-react-tools, this also requires version 2 or higher.

npm install pui-react-svg --save

npm install babel-loader react-svg-loader --save-dev

Props

Property Required Type Default Description
src yes String Name of the svg (excluding the .svg extension)

Basic usage

Import the subcomponents:

import {Svg} from 'pui-react-svg';

This is very difficult to run in the styleguide itself, so there is not a working example here, but it does work. The example below will render the file app/svg/search.svg.

<Svg src="search" width="20" height="20" />

By default, the Svg component will look in the app/svg folder at the root of your project (defined here as the location of your package.json). If you have svg files in other folders, you can subclass the Svg component as follows

import {Svg} from 'pui-react-svg';

class MySvg extends Svg {
  svgPathLoader(src) {
    return require(`!!babel-loader!react-svg-loader!./path/to/svgs/${src}.svg`);
  }
}

The path is relative to the file where you subclass the Svg component. Note that react-svg-loader will internally optimize your Svgs using svgo. This optimization will sometimes change your Svg in undesirable ways. You can turn off parts of the optimization with loader params. For example, the Svg component itself uses

require(`!!babel-loader!react-svg-loader?{"svgo":{"plugins":[{"removeUnknownsAndDefaults":false},{"cleanupNumericValues":false},{"removeUselessStrokeAndFill":false}]}}!../../app/svg/${src}.svg`);

Pivotal UI provides a set of commonly used icons in the Iconography Component For a full list of available icons, go to http://pivotalicons.cfapps.io.

Tables

npm install pui-react-table --save

npm install babel-loader react-svg-loader --save-dev

(The extra loaders are for the Iconography component.)

Props

Table

Property Required Type Default Description
columns yes Array Metadata about columns
CustomRow no Component The component to use when rendering table rows
data yes Array The data to display in the table
defaultSort no String The name of the column to use for sorting before user input

Items in 'Column'

Property Required Type Default Description
attribute yes String The key to use in the data prop to get data for that column
CustomCell no Component Component to use when rendering cells, defaults to TableCell
displayName no String The text in the TableHeader for that column
headerProps no Object React props that will be passed through to that column
sortable no Boolean false Is this column sortable? Defaults to false
sortBy no Function Function to transform data before sorting
cellClass no String Class to apply to all cells in a column

HTML Tables

The Table component is a robust component that offers a styled table with fully functioning sort. If the rows change, the content on the page will update.

Basic usage

Import the subcomponents:

import {Table, TableRow, TableCell} from 'pui-react-table';

The TableRow component is provided for users who wish to customize their rows with the CustomRow prop to Table. If a custom row is provided, the table will use that component to render each row, giving it a children prop representing the cells for that row and index representing the (zero-indexed) row number.

Note that sorting occurs on the actual data. Changing the presentation of the data does not affect the sort behavior.

The TableCell component is provided for users who wish to customize their cells with the CustomCell attribute on the columns prop. If a custom cell is provided, the table will use that component to render each cell, giving it a value prop representing the attribute from the datum for that row and index representing the (zero-indexed) row number. For more advanced use cases, the rowDatum prop is also passed into the custom cell.

Note that sorting occurs on the actual data. Changing the presentation of the data does not affect the sort behavior.

Flex Tables

The FlexTable component is similar to the Table component except it will build the underlying table as a flex grid instead of a traditional html table.

Basic usage

Import the subcomponents:

import {FlexTable, FlexTableRow, FlexTableCell} from 'pui-react-table';

The FlexTableRow component is provided for users who wish to customize their rows with the CustomRow prop to FlexTable.

The FlexTableCell component is provided for users who wish to customize their cells with the CustomCell attribute on the columns prop.

Tabs

npm install pui-react-tabs --save

Props

Tabs

Property Required Type Default Description
actions no Node An element or text that will display in the upper right
animation no Boolean false Whether to animate when moving between tabs, defaults to true
defaultActiveKey no Any The tab which will start out open. This should equal one of your tab's event keys
largeScreenClassName no String Will be applied to large screen tabs only
onSelect no Function Will override default behavior when clicking on a tab. If you want to retain the default behavior as well as add new functionality, change default active key in the function you provide
responsiveBreakpoint no oneOf('xs', 'sm', 'md', 'lg') The size at which the small-screen tabs (accordion-style) should switch to large-screen tabs (folder-style)
smallScreenClassName no String Will be applied to small screen tabs only
tabType no oneOf('simple', 'left') 'simple' Use 'left' to have the tabs stacked to the left

Tab

Property Required Type Default Description
aria-labelledby no String Overwrite the default aria-labelledby for the tab for more specific accessibility information
className no String ClassName to add to the tab content
disabled no Boolean false If true, disable the tab
eventKey no Any data representing the tab, to be used with defaultActiveKey or onSelect
onEntered no Function A function that gets called with the eventKey on entering a tab once animations have finished
onExited no Function A function that gets called with the eventKey on exiting a tab once animations have finished
title yes Node Text or an element rendered in the tab link
tabClassName no String className to add to the tab link

Basic usage

Import the subcomponents:

import {Tabs, Tab, LeftTabs} from 'pui-react-tabs';

Using Tab components in React consists of a parent element for the desired Tab type (for example, Tabs or LeftTabs). Each Tab is a child of this and has a tab property for the string value a Tab should display. Additionally, each Tab must define an eventKey property for uniquely identifying this tab to its parent component.

Tabs

Left

LeftTabs can be used to create tabs where the nav is stacked on the left. They take a few optional special properties in addition to the properties in Tabs.

Property Required? Type Description Default
tabWidth no number The number of bs columns for the tabs 6
paneWidth no number The number of bs columns for the tab content 24 - tabWidth

Responsive Breakpoints

Tabs can be responsive, and will display accordion-style on small screens and folder-style on large screens.

Tile Layout

npm install pui-react-tile-layout pui-react-panels --save

Props

Property Required Type Default Description
columns no oneOf(Number, Object) How many columns to display
noGutter no Boolean false Whether to include a gutter or not

Basic usage

Import the subcomponents:

import {TileLayout, TileLayoutItem} from 'pui-react-tile-layout';

// for the example
import {ClickableAltPanel} from 'pui-react-panels';

Responsive Breakpoints

You can also pass an object setting the number of columns for responsive breakpoints to the columns prop. You can set separate column values (from 1 - 12 columns) for some or all of xs, sm, md, lg, and xl screen sizes.

Gutters

You can make a TileLayout without gutters by passing noGutter as a prop.

Tooltips

npm install pui-react-tooltip --save

Tooltip

Props

Property Required Type Default Description
visible no Boolean true Whether the tooltip contents are visible
size no oneOf(['auto', 'sm', 'md', 'lg']) auto Size of the tooltip

The Tooltip component is a styled container for content that should be displayed when triggered by an OverlayTrigger or TooltipTrigger. It does not exhibit any dynamic behavior on its own.

OverlayTrigger vs TooltipTrigger

OverlayTriggers are highly configurable. Their associated overlays do not show up in the DOM until triggered. This makes them ideal for highly repeated layouts such as lists. TooltipTriggers are simpler to use, and their associated Tooltips are shown and hidden using css visibility rules. In contrast to OverlayTriggers, the markup always exists in the DOM.

OverlayTrigger

Props

Property Required Type Default Description
delay no Number Number of milliseconds to delay show and hide
delayHide no Number Number of milliseconds to delay hide
delayShow no Number Number of milliseconds to delay show
disableScrim no Boolean false Set to true to make tooltips stay open when clicking outside
display no Boolean false Whether or not to show the overlay
onEntered no Function Callback that is called after the overlay is shown
onExited no Function Callback that is called after the overlay is hidden
overlay no Node An element or text to overlay next to the target
pin no Boolean true Whether or not to reposition overlays to stay in the window
placement no oneOf('top', 'bottom', 'left', 'right') 'right' Placement of overlay in relation to target
theme no oneOf(['light', 'dark']) dark Theme of tooltip background and text
trigger no oneOf('hover', 'click', 'focus', 'manual') 'hover' Action to trigger showing overlay

Basic usage

Import the subcomponents:

import {Tooltip} from 'pui-react-tooltip';
import {OverlayTrigger} from 'pui-react-overlay-trigger';

To create a tooltip where the contents are not inlined with the triggering element itself, use the OverlayTrigger component. If the overlay property passed into the OverlayTrigger will be displayed on hover, this is where the Tooltip can be used. This can be useful in situations where you want to have many different elements trigger the same tooltip.

Tooltips are placed using the placement property on OverlayTrigger, "left", "right", "bottom", "top".

If trigger is set to manual, display of the tooltip is entirely determined by the display prop, which is controlled by the end user and not by OverlayTrigger.

TooltipTrigger

Props

Property Required Type Default Description
tooltip yes Node Tooltip content - will be wrapped in a Tooltip component
placement no oneOf(['left', 'right', 'bottom', 'top']) top Placement of tooltip in relation to target
trigger no oneOf(['hover', 'click']) hover Action to trigger showing tooltip
clickHideDelay no Number 1000 How long (in milliseconds) to wait before hiding after click
onEntered no Func () => {} Callback that is called after the tooltip is shown
onExited no Func () => {} Callback that is called after the tooltip is hidden
theme no oneOf(['light', 'dark']) dark Theme of tooltip background and text
size no oneOf(['auto', 'sm', 'md', 'lg']) auto Size of the tooltip

Basic usage

Import the subcomponents:

import {TooltipTrigger} from 'pui-react-tooltip';

TooltipTriggers are an easy way to create CSS-driven tooltips with the tooltip content created inline with the triggering element. The content of the tooltip is wrapped in a Tooltip component for ease of styling. Please note that the TooltipTrigger will add a lot of markup to the DOM if you are using it in a highly repeated layout.

Since the tooltip property is of type Node, you may add markup to the tooltip, such as links.

This documentation generated using Hologram