Xerum

Getting Started

Installation and Use

npm i xerum

yarn add xerum

Then destructure the component in the file using import — example:

import { Button } from 'xerum';

This library has the following peer dependencies:

@fortawesome/fontawesome-free (v6+)
formik (v2+)
GSAP (v3+)
lodash (v4+)
moment (v2+)
react-beautiful-dnd (v13+)

Note: Unless noted otherwise, you can pass standard attributes as you would with any element or React component — for example: disabled, target, style, className etc.

Buttons

<Button />

NAME
DESCRIPTION
DEFAULT
Name:
btnType
Description:
solid, ghost or transparent.
Default:
solid
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-check".
Default:
—
Name:
text
Description:
Primary text to display.
Default:
—
Name:
hoverStyle
Description:
For hover styles that need to be handled dynamically.
Default:
—
Name:
callback
Description:
Generic click handler for route changes or other functions.
Default:
—
Name:
passthrough
Description:
Stops event propagation and allows callback if parent click event overrides callback.
Default:
—
Name:
url
Description:
Used explicitly for making external site calls.
Default:
—

Tip: The passthrough prop is handy if your

<Button />

component is a child of an element that already has a click event — i.e. within a table data cell of a table row, where the table row has a row click handler that overrides the button's click event.

Button Example

<Button
  icon="fa-brands fa-google"
  style={{ backgroundColor: blue }}
  hoverStyle={{ backgroundColor: darkBlue }}
  url="google.com"
/>

<Button
  text="Submit"
  type="submit"
  disabled={isSubmitting}
  btnType="ghost"
  callback={handleSubmit}
/>

<Button
  icon="fa-solid fa-pencil-alt"
  text="Edit Profile"
  btnType="transparent"
  callback={editProfile}
/>

Containers

<Accordion />

NAME
DESCRIPTION
DEFAULT
Name:
sections
Description:
Array of objects that describes each section. Objects must include { title, content } keys. An optional color key with valid hex formatting can be included to quickly color the entire section.
Default:
—
Name:
openDefault
Description:
Deafult section to expand on load.
Default:
—
Name:
openIcon
Description:
Font Awesome i.e. "fa-solid fa-minus".
Default:
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-plus".
Default:
Name:
noIcon
Description:
Removes the open and close section icons.
Default:
—
Name:
callback
Description:
Generic function to run when the active section changes. Receives new section.
Default:
—

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .section {}

.yourClassName .section .title {}

.yourClassName .section .title:hover {}

.yourClassName .section .title.active {}

.yourClassName .section .title.active:hover {}

.yourClassName .section .title i {}

.yourClassName .section .content {}

Your custom className will apply to the

<Accordion />

container by default.

Accordion Example

First section

Section 1 content

Second section

Third section

const sections = [
  {
    title: "First section",
    content: "Section 1 content",
  },
  {
    title: "Second section",
    content: "Section 2 content",
  },
  {
    title: "Third section",
    content: "Section 3 content",
  },
];

<Accordion
  sections={sections}
  openDefault={sections[0]}
/>

<Card />

NAME
DESCRIPTION
DEFAULT
Name:
image
Description:
Thumbnail image to render on card.
Default:
—
Name:
title
Description:
Title text to display on card.
Default:
—
Name:
titleColor
Description:
Sets the color of the title text using hex format, i.e. #000 or #000000.
Default:
#0d97ff
Name:
text
Description:
Preview text to display on card.
Default:
—
Name:
limit
Description:
Limits the length of the preview text by character -- will stop at the nearest whole word closest to given character limit.
Default:
96
Name:
footer
Description:
Enables the card footer for additional information. Takes a string or element.
Default:
true
Name:
url
Description:
External url to open if image or title is clicked.
Default:
—
Name:
vertical
Description:
Changes the default horizontal layout of the Card to vertical.
Default:
—

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .image {}

.yourClassName .text .title {}

.yourClassName .footer {}

Your custom className will apply to the

<Card />

container by default.

Card Example

Horizontal:

Card Title...

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut...

Vertical:

Card Title...

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut...

<Card
  image="your-thumb-url.[ext]"
  title="Card Title..."
  text={yourPreviewText}
  limit={96}
  footer="Image credit: iStock Photo"
  url="https://google.com"
  vertical
/>

<Confirm />

NAME
DESCRIPTION
DEFAULT
Name:
title
Description:
Title to display in confirm dialogue.
Default:
—
Name:
titleColor
Description:
Sets the color of the title text using hex format, i.e. #000 or #000000.
Default:
—
Name:
message
Description:
Primary message to display in confirm dialogue.
Default:
—
Name:
confirmText
Description:
Text to display on the confirm button.
Default:
Okay
Name:
cancelText
Description:
Text to display on the cancel button.
Default:
Cancel
Name:
onConfirm
Description:
Generic event handler when confirm button is clicked. This should not toggle state visibility and is reserved only for your API call or other action.
Default:
—
Name:
onCancel
Description:
Generic event handler when cancel button is clicked. This should toggle state visibility.
Default:
—
Name:
bgClose
Description:
Allows click event on the confirm background to trigger the onCancel handler.
Default:
false

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .title {}

.yourClassName .message {}

.yourClassName .confirm button {}

.yourClassName .cancel button {}

Your custom className will apply to the

<Confirm />

container by default.

Confirm Example

const [ visible, setVisible ] = useState(false);

(visible && (
  <Confirm
    title="Confirm Title..."
    message="You have asked the user to respond."
    onConfirm={yourAPICall}
    onCancel={() => setVisible(!visible)}
    bgClose
  />
)}

NAME
DESCRIPTION
DEFAULT
Name:
title
Description:
Title to display in the Modal window.
Default:
—
Name:
titleColor
Description:
Sets the color of the title text and close icon hover state using hex format, i.e. #000 or #000000.
Default:
—
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-xmark".
Default:
Name:
onClose
Description:
Generic event handler when close button is clicked — your state action for controlling visibility should be passed here.
Default:
—
Name:
bgClose
Description:
Allows click event on the modal background to trigger the onClose handler.
Default:
false

Modal Example

const [ visible, setVisible ] = useState(false);

{visible && (
  <Modal
    title="Modal title..."
    onClose={() => setVisible(!visible)}
    bgClose
  >
    <p>Modal content...</p>
  </Modal>
)}

<SlideOver />

NAME
DESCRIPTION
DEFAULT
Name:
title
Description:
Title to display in the Slide-Over panel.
Default:
—
Name:
titleColor
Description:
Sets the color of the title text and close icon hover state using hex format, i.e. #000 or #000000.
Default:
—
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-arrow-right-long".
Default:
Name:
onClose
Description:
Generic event handler when close button is clicked — your state action for controlling visibility should be passed here.
Default:
—

Slide-Over Example

const [ visible, setVisible ] = useState(false);

{visible && (
  <SlideOver
    title="Slide-Over title..."
    onClose={() => setVisible(!visible)}
  >
    <p>Slide-Over content...</p>
  </SlideOver>
)}

<Table />

NAME
DESCRIPTION
DEFAULT
Name:
content*
Description:
Object description of headers and rows.
Default:
—
Name:
sortable
Description:
Enables headers to sort table by ascending/descending column results when clicked — receives newly sorted array.
Default:
—
Name:
defaultSort
Description:
Default column to sort — must be an existing header string from your headers array.
Default:
headers[0]
Name:
draggable
Description:
Enables manual sort order manipulation of table rows via drag and drop — receives newly sorted array.
Default:
—
Name:
dragIcon
Description:
Font Awesome i.e. "fa-solid fa-grip-vertical".
Default:
Name:
labelColor
Description:
Sets the color of the label text using hex format, i.e. #000 or #000000.
Default:
#f5f5f5
Name:
labelBG
Description:
Sets the color of the label background using hex format, i.e. #000 or #000000.
Default:
#20232a
Name:
columnLayout
Description:
Overrides dynamically created, evenly spaced, columns with grid-based formatting i.e. "10rem 1fr 7rem" or "repeat(3, 1fr)".
Default:
-

*Required Prop.

Note: Add an onClick function to your row object;

rows: [{ ...tData, onClick }]

or a label key/value for labels;

rows: [{ ...tData, label }]

— ideal labels are under six characters.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .header {}

.yourClassName li {}

Your custom className will apply to the

<Table />

container by default.

Table Example

Bird Name
Flight Speed (MPH)
Medium
Bird Name:
Raven
Flight Speed Mph:
50
Large
Bird Name:
Golden Eagle
Flight Speed Mph:
200
Small
Bird Name:
Sparrow
Flight Speed Mph:
—

Use headers or drag rows to sort —Drag row to sort or click row for callback.

const [ content, setContent ] = useState({
  headers: [ "Bird Name", "Flight Speed (MPH)" ],
  rows: [
    {
      td1: "Sparrow",
      td2: null,
      onClick: () => rowHandler("Sparrow"),
      label: "Small",
    },
    {
      td1: "Golden Eagle",
      td2: 200,
      onClick: () => rowHandler("Eagle"),
      label: "Large",
    },
    {
      td1: "Raven",
      td2: 50,
      onClick: () => rowHandler("Raven"),
      label: "Medium",
    },
  ],
});

const flightSpeed = content.headers[1];
const receivedArr = sortedArr => {
  // Normalize or send to state directly.
  setContent({ ...content, rows: sortedArr })
};

<Table
  content={content}
  defaultSort={flightSpeed}
  sortable={receivedArr}
  draggable={receivedArr}
/>

<Tabs />

NAME
DESCRIPTION
DEFAULT
Name:
content*
Description:
Array of objects containing { name, content } keys, where name is the friendly name shown on the tab and content is the content to be rendered.
Default:
—
Name:
activeColor
Description:
Sets the color of the active tab background using hex format, i.e. #000 or #000000.
Default:
#0d97ff
Name:
inactiveColor
Description:
Sets the color of the inactive tab background using hex format, i.e. #000 or #000000.
Default:
#4d5153

*Required prop.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .tabNames {}

.yourClassName .tabNames .name {}

.yourClassName .tabNames .name.active {}

.yourClassName .tabSlider {}

Your custom className will apply to the

<Tabs />

container by default.

Tabs Example

Tab 1

Tab 2

Tab 3

Content 1

const content = [
  { name: "Tab 1", content: "Content 1" },
  { name: "Tab 2", content: "Content 2" },
  { name: "Tab 3", content: "Content 3" },
];

<Tabs content={content} />

Data

<Label />

NAME
DESCRIPTION
DEFAULT
Name:
text
Description:
Text to show on label — overrides children.
Default:
—
Name:
color
Description:
Sets the color of the label text using hex format, i.e. #000 or #000000.
Default:
#f5f5f5
Name:
bgColor
Description:
Sets the background color of the label using hex format, i.e. #000 or #000000.
Default:
#20232a
Name:
useClose
Description:
Enabled label close icon.
Default:
—
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-circle-xmark".
Default:
Name:
callback
Description:
Generic click handler for controlling label removal when useClose is true.
Default:
—

Use the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName i.labelClose {}

Your custom className will apply to the

<Label />

container by default.

Label Example

child...

Removable

Custom

const white = #ffffff;
const blue = #0d97ff;

<Label>
  <i className="fa-solid fa-child" />&nbsp;
  child...
</Label>

<Label text="Removable"
  useClose
  callback={() => console.log("Closed")}
/>

<Label text="Custom"
  useClose
  closeIcon="fa-solid fa-xmark"
  color={white}
  bgColor={blue}
/>

<Percent />

NAME
DESCRIPTION
DEFAULT
Name:
current
Description:
Current value to divide with.
Default:
—
Name:
total
Description:
Total value to divide by.
Default:
—
Name:
limit
Description:
Limits the decimal placement count.
Default:
2
Name:
usePlus
Description:
true or false. Enables the "+" symbol preceding positive percent values.
Default:
false
Name:
positiveColor
Description:
Sets the color of a positive result using hex format, i.e. #000 or #000000.
Default:
—
Name:
negativeColor
Description:
Sets the color of a negative result using hex format, i.e. #000 or #000000.
Default:
—

Percent Example

+5,805.71 %

const blue = "#0d97ff";

<Percent
  current={3483.432}
  total={60}
  positiveColor={blue}
  usePlus
/>

<Price />

NAME
DESCRIPTION
DEFAULT
Name:
value
Description:
Amount to be rendered.
Default:
0
Name:
limit
Description:
Limits the decimal placement count.
Default:
2
Name:
symbol
Description:
Symbol of currency that precedes value. Takes a string or more custom solution within React tags.
Default:
$
Name:
currency
Description:
Three to four letter abbreviated currency, i.e. USD, GBP, YUAN etc.
Default:
—
Name:
positiveColor
Description:
Sets the positive color of value using hex format, i.e. #000 or #000000.",
Default:
—
Name:
negativeColor
Description:
Sets the negative color of value using hex format, i.e. #000 or #000000.",
Default:
—

Price Example

1,024.76623496 ETH

const blue = "#0d97ff";

<Price
  value={1024.76623496782}
  symbol={
    <Fragment>
      <i className="fa-brands fa-ethereum" />
    </Fragment>
  }
  currency="ETH"
  limit={8}
  positiveColor={blue}
/>

<Progress />

NAME
DESCRIPTION
DEFAULT
Name:
current
Description:
Current value to divide with.
Default:
—
Name:
total
Description:
Total value to divide by.
Default:
—
Name:
fixedPct
Description:
Keeps percent value fixed instead of following the progress bar.
Default:
false
Name:
noPct
Description:
Disables percent value.
Default:
false
Name:
color
Description:
Sets the color of the progress bar using hex format, i.e. #000 or #000000.
Default:
#0d97ff
Name:
bgColor
Description:
Sets the color of the progress track using hex format, i.e. #000 or #000000.
Default:
#4d5153
Name:
pctColor
Description:
Sets the color of the percent value using hex format, i.e. #000 or #000000.
Default:
#00000080

Note: Use the color, bgColor and pctColor props if you need custom colors.

Use the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .progress .pct {}

Your custom className will apply to the

<Progress />

container by default.

Progress Example

60.47 %

<Progress
  current={4354.432}
  total={7200}
  pctColor="#ffffff"
/>

Feedback

<Badge />

NAME
DESCRIPTION
DEFAULT
Name:
count
Description:
Integer count to be displayed — will not display if falsey.
Default:
—
Name:
square
Description:
Overrides default circle styling with rounded square corners.
Default:
—

The

<Badge />

component works well when placed as a child insde the

<Button />

component. You are also free to place it on any component you please — the important thing is that a custom className or style prop with position data should be passed to get proper placement. The associated examples use the following CSS:

.pos {
  top: -2.55rem;
  right: -1.55rem;
}

Badge Example

1,296

// Default
<Button icon="fa-solid fa-bell">
  <Badge className="pos" count={4} />
</Button>

// Square
<Button icon="fa-solid fa-envelope">
  <Badge className="pos" count={1296} square />
</Button>

NAME
DESCRIPTION
DEFAULT
Name:
text
Description:
Text to show on banner — overrides children.
Default:
—
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-times".
Default:
Name:
noClose
Description:
Disables banner close icon.
Default:
—
Name:
callback
Description:
Generic click handler, typically for controlling banner state.
Default:
—
Name:
center
Description:
Center justifies banner text or children.
Default:
—
Name:
round
Description:
Overrides default corner styling with round corners.
Default:
—

Note: The

<Banner />

component will take up all of the available width in its parent container by default.

Banner Example

const icon = "fa-solid fa-triangle-exclamation";

<Banner
  center
  round
  noClose
  className="customBanner"
  callback={handleClose}
>
  <i className={icon} />
  <strong>Reminder</strong>:
  Servers will be down.
</Banner>

<FieldError />

NAME
DESCRIPTION
DEFAULT
Name:
name*
Description:
Name of field to validate — must match reference field name, exactly.
Default:
—

*Required Prop.

Note: The

<FieldError />

component uses Formik for field state management and should be used within Formik's

<Form />

tag. The associated example shows a proper Formik setup with yup handling validation rules.

FieldError Example

import Formik from 'formik';
import * as yup from 'yup';

const defaults = { email: "" };
const schema = yup.object().shape({
  email: yup
    .string()
    .email('Invalid email.')
    .required('Field is required.')
    .trim(),
});

const handleSubmit = args => {
  const { values, setSubmitting } = args;
  // Your submit action from state...
};

<Formik
  initialValues={defaults}
  validationSchema={schema}
  enableReinitialization={true}
  onSubmit={(values, { setSubmitting }) => {
    handleSubmit({ values, setSubmitting });
  }}>
    {form => (
      <Form>
        <Field type="text" name="email" />
        <FieldError name="email" />
        <Button type="submit" />
      </Form>
    )}
</Formik>

<FieldReqs />

NAME
DESCRIPTION
DEFAULT
Name:
value*
Description:
Current value of the associated field to check against.
Default:
—
Name:
upper
Description:
Adds an uppercase requirement.
Default:
—
Name:
lower
Description:
Adds a lowercase requirement.
Default:
—
Name:
number
Description:
Adds a number requirement.
Default:
—
Name:
min
Description:
Adds a minimum length requirement.
Default:
8
Name:
special
Description:
Adds a special character requirement — pass a custom string to override default.
Default:
@#$%^&+=!
Name:
exclude
Description:
Array of objects for custom exclusion. Objects must be { display, value }. Where display is the friendly name shown and value is the exclusion.
Default:
—
Name:
color
Description:
Sets the active color of a valid icon using hex format, i.e. #000 or #000000.
Default:
#0d97ff
Name:
exColor
Description:
Sets the active color of an exclusion icon using hex format, i.e. #000 or #000000.
Default:
#c93434
Name:
bgColor
Description:
Sets the inactive color of all icons using hex format, i.e. #000 or #000000.
Default:
#aab2b8

*Required Prop.

Note: The

<FieldReqs />

component is not responsible for field validation on submit — it is simply visual feedback so the user can correct any validation issues prior to submitting.

FieldReqs Example

Uppercase
Lowercase
Number
8 Minimum
Special: @ # $ % ^ & + = !
First name
Last name

const [ inputVal, setInputVal ] = useState("");

const fName = "Bob";
const lName = "Belcher";

<input
  type="password"
  placeholder="Type password to test..."
  onChange={e => {
    setInputVal(e.currentTarget.value);
  }}
/>

<FieldReqs
  value={inputVal}
  upper
  lower
  number
  min
  special
  exclude={[
    { display: "First name", value: fName },
    { display: "Last name", value: lName },
  ]}
/>

<Loading />

NAME
DESCRIPTION
DEFAULT
Name:
isLoading*
Description:
true or false — derived from loading selector managed in app state on specific resource API call start/end.
Default:
true
Name:
hasData*
Description:
true or false — derived from data returned (or not) after server response.
Default:
false
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-spinner".
Default:
Name:
text
Description:
Your text or component to display while API call is being made.
Default:
Loading...
Name:
failIcon
Description:
Font Awesome i.e. "fa-solid fa-exclamation-circle".
Default:
Name:
failText
Description:
Your text or component to display if loading/API call is complete and no data was returned or set in app state.
Default:
Load failed.
Name:
noIcon
Description:
Disables load/fail icons.
Default:
—
Name:
noText
Description:
Disables load/fail text.
Default:
—

*Required prop.

Tip: You can get creative by disabling the icon and passing your own component as the text — such as the

<Progress />

component — or try passing a style attribute and change the color of the loader based on isLoading and hasData.

Loading Example

Load ready

Fail ready

// General use
<Loading
  isLoading={contentLoading}
  hasData={contentData}
>
  {/*
    Your content after loading has finished
    and 200 response data set in app state.
  */}

  <i className="fa-solid fa-thumbs-up" />
  All good.
</Loading>

<NotFound />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-bug".
Default:
Name:
noIcon
Description:
Disabled not found icon.
Default:
—
Name:
title
Description:
Sets a custom, heavily-weighted title.
Default:
404: Hrmm...
Name:
noTitle
Description:
Disables not found title.
Default:
—
Name:
message
Description:
Sets a custom message.
Default:
Can't find that page.
Name:
noMessage
Description:
Disables not found message.
Default:
—

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName h2 {}

.yourClassName p {}

Your custom className will apply to the

<NotFound />

container by default.

Not Found Example

404: Hrmm...

Can't find that page.

<NotFound />

<Notifications />

NAME
DESCRIPTION
DEFAULT
Name:
notifications*
Description:
Array of notifications. Array values must be a string or an object with the following keys: { message, type, icon } all string values, with icon being Font Awesome — type must be success, warning or error.
Default:
—
Name:
removeNotification*
Description:
Action from app state responsible for removing a notification from state — receives the index to remove.
Default:
—
Name:
time
Description:
Time (milleseconds) before notification self-closes.
Default:
4 seconds
Name:
noTime
Description:
Disables self-closing timer, user must manually close notification.
Default:
—
Name:
noIcons
Description:
Disables notification icons.
Default:
—

*Required prop.

Note: You will first need to have an existing notifications array selector and corresponding addNotification action set up in app state. Then, at the root of your app, place

<Notifications />

with that action/selector pair passed in the props.

Now any component event or API callback that triggers your addNotification action will trigger notifications.

Notifications Example

const newNotification = "You've been notified!";

// 1. Ready action/selector array in app state.
const [ notifications, setNotifications ] = useState([]);

const addNotification = notification => {
  setNotifications([ ...notifications, notification ]);
};

const removeNotification = index => {
  const updatedArray = notifications.filter((item, i) => {
    if (index !== i) return item;
  };

  setNotifications(updatedArray);
};

// 2. Place Notifications component
// in root component and pass the
// notifications array action/selector.
<Notifications
  time={3000}
  notifications={notifications}
  removeNotification={removeNotification}
/>

// 3. Trigger notification action from any
// component event or API callback.
<Button
  text="Click to Notify"
  callback={() => addNotification(newNotification)}
/>

Form Extras

<Checkbox />

NAME
DESCRIPTION
DEFAULT
Name:
name*
Description:
Name of field, for validation.
Default:
—
Name:
label
Description:
String to display to the right of the checkbox.
Default:
—
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-check".
Default:
Name:
boxColor
Description:
Sets the color of the check box using hex format, i.e. #000 or #000000.
Default:
#7e8489
Name:
checkColor
Description:
Sets the color of the check mark using hex format, i.e. #000 or #000000.
Default:
#0d97ff

*Required Prop.

Note: The

<Checkbox />

component uses Formik for field state management and should be used within Formik's

<Form />

tag. The associated example shows a proper Formik setup with yup handling validation rules.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .markContainer .box {}

.yourClassName .markContainer .check {}

Your custom className will apply to the

<Checkbox />

container by default.

Checkbox Example

import Formik from 'formik';
import * as yup from 'yup';

const defaults = { sampleCheckbox: false };
const schema = yup.object().shape({
  sampleCheckbox: yup
    .bool()
    .oneOf([true], 'Field is required.')
});

const handleSubmit = args => {
  const { values, setSubmitting, resetForm } = args;
  // Your submit action from state...
};

<Formik
  initialValues={defaults}
  validationSchema={schema}
  enableReinitialization={true}
  onSubmit={(values, { setSubmitting, resetForm }) => {
    const args = { values, setSubmitting, resetForm };
    handleSubmit(args);
}}>
  {form => (
    <Form>
      <Checkbox
        name="sampleCheckbox"
        label="I agree to the Terms."
      />

      <div>
        <FieldError name="sampleCheckbox" />
      </div>

      <Button type="submit" />
    </Form>
  )}
</Formik>

<Toggle />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-circle".
Default:
Name:
iconColor
Description:
Sets the color of the toggle icon using hex format, i.e. #000 or #000000.
Default:
#f5f5f5
Name:
inactiveColor
Description:
Sets the inactive color of the toggle track using hex format, i.e. #000 or #000000.
Default:
#5d6166
Name:
activeColor
Description:
Sets the active color of the toggle track using hex format, i.e. #000 or #000000.
Default:
#0d97ff
Name:
callback
Description:
Generic handler that receives new toggle value of true or false.
Default:
—

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName input {}

.yourClassName .toggleTrack {}

.yourClassName .toggleTrack i {}

Your custom className will apply to the

<Toggle />

container by default.

Toggle Example

<Toggle />

Information

<Copyright />

NAME
DESCRIPTION
DEFAULT
Name:
name*
Description:
Your name, company/organization etc. the copyright belongs to.
Default:
—
Name:
trade
Description:
Displays a registered trademark symbol in addition to the copyright.
Default:
—
Name:
rights
Description:
Displays an additional message with your copyright.
Default:
All rights reserved.

* Required prop.

Copyright Example

<Copyright name="Your Name" />

<Copyright name="Company, LLC" rights trade />

<Copyright
  name="Organization"
  rights="made with love."
/>

NAME
DESCRIPTION
DEFAULT
Name:
networks*
Description:
Array of objects with name, path and icon keys.
Default:
icon:
Name:
noText
Description:
Disables network name text, if it exists.
Default:
—
Name:
column
Description:
Stacks network icon and name.
Default:
—
Name:
asTooltip
Description:
Displays network name as a tool tip on icon hover.
Default:
—
Name:
tipPosition
Description:
top, right, bottom or left.
Default:
Lower-right of cursor.

*Required prop.

Note: Not including or leaving an empty name key in your networks array object will also have the same effect as passing the noText prop. Though asTooltip and noText may look the same, noText will not render the name of the network on hover.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName a {}

.yourClassName a i {}

.yourClassName .tooltip {}

Your custom className will apply to the

<Social />

container by default.

Social Example

const socialNetworks = [
  {
    name: "Twitter",
    path: "https://twitter.com",
    icon: "fa-brands fa-twitter" },
  {
    name: "Facebook",
    path: "https://facebook.com",
    icon: "fa-brands fa-facebook" },
  {
    name: "Instagram",
    path: "https://instagram.com",
    icon: "fa-brands fa-instagram"
  },
];

<Social
  asTooltip
  tipPosition="top"
  networks={socialNetworks}
/>

<Social networks={socialNetworks} />
<Social networks={socialNetworks} column />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-info-circle".
Default:
Name:
text
Description:
Text to show on hover — overrides children.
Default:
—
Name:
position
Description:
top, right, bottom or left.
Default:
Lower-right of cursor.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .tip {}

.yourClassName i {}

Your custom className will apply to the

<Tooltip />

container by default.

Tooltip Example

Standard

Child

// Standard
<Tooltip text="Standard tool tip." />

// Child
<Tooltip position="top">
  <i className="fa-solid fa-smile" />
  Tool tip rendering children.
</Tooltip>

<Menu />

NAME
DESCRIPTION
DEFAULT
Name:
links
Description:
Array of objects that describes links, sub-menu's etc.
Default:
—
Name:
openIcon
Description:
Font Awesome i.e. "fa-solid fa-caret-down".
Default:
Name:
closeIcon
Description:
Font Awesome i.e. "fa-solid fa-caret-right".
Default:

Note: Your links array must contain objects with the following keys:

{
  name, // Friendly name to display on menu.
  path, // i.e. "/link-path" or "#link-path".
  icon, // Font Awesome string.
  subMenu: [] // Optional array of objects.
}

Any subMenu array objects should follow the same object key format above. You can nest more sub-menus this way, if needed.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .topLevel {}

.yourClassName .topLevel .icon {}

.yourClassName .topLevel .subMenuIcon {}

Your custom className will apply to the

<Menu />

container by default.

Menu Example

const links = [
  {
    name: "Home",
    path: "#home",
    icon: "fa-solid fa-home"
  },
  {
    name: "Settings",
    path: "#settings",
    icon: "fa-solid fa-gears"
  },
  {
    name: "My account",
    path: "#account",
    icon: "fa-solid fa-user",
    subMenu: [
      { name: "Info", path: "#Info" },
      { name: "Billing", path: "#billing" },
    ],
  },
];

<Menu
  links={links}
  openIcon="fa-solid fa-plus"
  closeIcon="fa-solid fa-minus"
/>

<Pagination />

NAME
DESCRIPTION
DEFAULT
Name:
totalPages
Description:
Total page count, as received from your server.
Default:
1
Name:
currentPage
Description:
Current page, as received from your server.
Default:
1
Name:
onPageChange
Description:
Generic event handler when page number/icons or prev/next buttons are clicked. Receives new page number for your API page data request.
Default:
—
Name:
prevIcon
Description:
Font Awesome i.e. "fa-solid fa-angles-left".
Default:
Name:
pageIcon
Description:
Font Awesome i.e. "fa-solid fa-circle".
Default:
Name:
nextIcon
Description:
Font Awesome i.e. "fa-solid fa-angles-right".
Default:

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName .prev {}

.yourClassName .pageNum {}

.yourClassName .next {}

Your custom className will apply to the

<Pagination />

container by default.

Pagination Example

const res = {
  total_pages: 5,
  current_page: 1,
  page_size: 30,
  page_data, // Arr 150 length
};

<Pagination
  totalPages={res.total_pages}
  currentPage={res.current_page}
  onPageChange={page => req({ page })}
/>

<Pagination
  totalPages={res.total_pages}
  currentPage={res.current_page}
  onPageChange={page => req({ page })}
  prevIcon="fa-solid fa-arrow-left"
  pageIcon="fa-solid fa-square"
  nextIcon="fa-solid fa-arrow-right"
/>

Query

<Filter />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-filter".
Default:
Name:
noIcon
Description:
Removes the filter field icon.
Default:
—
Name:
data
Description:
Main data object with at least one { key: value } pair.
Default:
—
Name:
include
Description:
Array of key names from your data object to include in filter results — use dot notation to access nested keys, i.e. "key.subKey.anotherKey"
Default:
—
Name:
callback
Description:
Generic handler that receives filtered array results.
Default:
—

Note: Unlike the

<Search />

component, the

<Filter />

component filters existing DOM elements in real-time — it does not use any external API callbacks.

Tip: The

<Filter />

component allows for powerful filtering. You can type in partial words, numbers, a single letter or multiple words in the same field to see all query results at once.

When accessing an array of objects, keep the dot notation going to drill into the final key you want to use as a filter value. It is assumed that all objects in your array of objects have identical structure — see associated example.

Filter Example

Results (9):

USDC

USD

GBP

EUR

BTC

ETH

XRP

ADA

DOT

// 1. Set hook to receive filtered data.
const [ filtered, setFiltered ] = useState([]);

const data = {
  stableCoin: "USDC",
  currencies: {
    pairs: [ "USD", "GBP", "EUR" ],
    crypto: [
      { rawData: { symbol: "BTC" } },
      { rawData: { symbol: "ETH" } },
      { rawData: { symbol: "XRP" } },
      { rawData: { symbol: "ADA" } },
      { rawData: { symbol: "DOT" } },
    ],
  },
};

<Filter
  data={data}
  placeholder="Partial or multiple words..."
  include={[
    "stableCoin",
    "currencies.pairs",
    "currencies.crypto.rawData.symbol",
  ]}

  // 2. set filtered data to use for
  // conditional rendering...
  callback={newData => setFiltered(newData)}
/>

<Search />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-magnifying-glass".
Default:
Name:
noIcon
Description:
Removes the search field icon.
Default:
—
Name:
noButton
Description:
Removes the search field submit button. Submit can be triggered with the "Enter" key.
Default:
—
Name:
btnText
Description:
Text to display on search button.
Default:
Search
Name:
btnClassName
Description:
Your className string to forward to the button element.
Default:
—
Name:
callback
Description:
Generic event handler when search button is clicked.
Default:
—

Note: Passing a standard className prop will affect the input field by default.

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName form {}

.yourClassName form label {}

.yourClassName form label i {}

.yourClassName form label input {}

.yourClassName form button {}

Your custom className will apply to the

<Search />

container by default.

Search Example

<Search
  btnText="Find it"
  placeholder="Find something..."
  callback={val => {
    const payload = { yourQueryKey: val };

    // Your API action...
    sendToAPI(payload);
  }} />

Utility

<AggTimer />

NAME
DESCRIPTION
DEFAULT
Name:
timeframe
Description:
seconds, minutes, hours, days, weeks or months.
Default:
hours
Name:
aggregate
Description:
Aggregation for timeframe, i.e. new time range interval every 3rd day in the week or 15m in the hour etc.
Default:
1
Name:
local
Description:
Overrides UTC and uses local time.
Default:
UTC
Name:
limit
Description:
Limits display length. i.e. limit of 3 for months as MM:WW:DD vs MM:WW:DD:hh:mm:ss
Default:
—
Name:
compact
Description:
Removes friendly units and compresses space between time spots, i.e. 00:00:00
Default:
—
Name:
callback
Description:
Function to execute when timer reaches the end of it's range.
Default:
—

AggTimer Example

0M 4W 0D 15h 38m 53s

Overview

Timeframe: Months (12 months/year)

Aggregate: Every 3 months (4 total)

From: Wed, 1/1/2025, 12:00:00 AM

To: Thu, 1/1/2026, 12:00:00 AM

UTC: true

Aggregate Range (3/4)

Start: Tue, 7/1/2025, 12:00:00 AM

Now: Tue, 9/2/2025, 08:21:06 AM

End: Wed, 10/1/2025, 12:00:00 AM

<AggTimer timeframe="months" aggregate={3} />

<AuthRoute />

NAME
DESCRIPTION
DEFAULT
Name:
auth
Description:
true or false.
Default:
—
Name:
redirect
Description:
Path of authentication page to redirect to if token is invalid.
Default:
/login

<AuthRoute />

should be placed in React Router's element prop, with the actual

<Route />

you are protecting as a child component. Please see the code sample as well as React Router's docs for details regarding proper

<Route />

usage.

Note: The value of the auth prop should come from the result of your token validation process in app state.

Auth. Route Example

Route Locked

User will see auth. route only.
(Sample auth form below)

<Routes>
  <Route element={<AuthRoute auth={token} />}>
    <Route path="/" element={<Content />} />
  </Route>
</Routes>

<Heartbeat />

NAME
DESCRIPTION
DEFAULT
Name:
time
Description:
Time (milleseconds) between connection tests.
Default:
60 seconds
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-ethernet".
Default:
Name:
text
Description:
Text to display on connection fail.
Default:
No connection detected.
Name:
disabled
Description:
true or false.
Default:
—

Tip: It is recommended to pass your NODE_ENV flag/conditional to the disabled prop.

Note: This component will not render to the DOM until the internet connection goes out — your main

<App />

is rendered by default. You may need to wait, at most, 60 seconds before the change happens since that is the default interval.

Heartbeat Example

Online: Rendering Dev. App...
(no connection checks)

... or disable your N.I.C. for the real deal.

import process from 'process';

const { env: { NODE_ENV } } = process;
const dev = NODE_ENV !== "production";

// Wrap your main App with Heartbeat.
<Heartbeat disabled={dev}>
  <App />
</Heartbeat>

<Status />

NAME
DESCRIPTION
DEFAULT
Name:
color
Description:
Sets the color of the indicator using hex format, i.e. #000 or #000000.
Default:
#7e8489
Name:
text
Description:
Text to display next to service indicator.
Default:
—

Note: The examples provided are hard-coded for clarity, but should receive their colors, dynamically, from app state.

Status Example

App servers

Media servers

Email sending

const green = "#50b990";
const yellow = "#f0b800";
const red = "#c93434";

<Status color={green} text="App servers" />
<Status color={yellow} text="Media servers" />
<Status color={red} text="Email sending" />

<ToTop />

NAME
DESCRIPTION
DEFAULT
Name:
icon
Description:
Font Awesome i.e. "fa-solid fa-angle-up".
Default:
Name:
iconColor
Description:
Sets the color of the icon using hex format, i.e. #000 or #000000.
Default:
#f5f5f5
Name:
bgColor
Description:
Sets the color of the background using hex format, i.e. #000 or #000000.
Default:
#20232a

Tip: You can target the following CSS heirarchy for custom styling:

.yourClassName {}

.yourClassName i {}

Your custom className will apply to the

<ToTop />

container by default.

To-Top Example

<ToTop
  icon="fa-solid fa-angles-up"
/>

Getting Started

Installation and Use

Buttons

<Button />

Button Example

Containers

<Accordion />

Accordion Example

First section

Second section

Third section

<Card />

Card Example

<Confirm />

Confirm Example

<Modal />

Modal Example

<SlideOver />

Slide-Over Example

<Table />

Table Example

<Tabs />

Tabs Example

Data

<Label />

Label Example

<Percent />

Percent Example

<Price />

Price Example

<Progress />

Progress Example

Feedback

<Badge />

Badge Example

<Banner />

Banner Example

<FieldError />

FieldError Example

<FieldReqs />

FieldReqs Example

<Loading />

Loading Example

<NotFound />

Not Found Example

404: Hrmm...

<Notifications />

Notifications Example

Form Extras

<Checkbox />

Checkbox Example

<Toggle />

Toggle Example

Information

<Copyright />

Copyright Example

<Social />

Social Example

<Tooltip />

Tooltip Example

Navigation

<Menu />

Menu Example

<Pagination />

Pagination Example

Query

<Filter />

Filter Example

<Search />

Search Example

Utility

<AggTimer />

AggTimer Example

Overview

Aggregate Range (3/4)

<AuthRoute />

Auth. Route Example

<Heartbeat />

Heartbeat Example

<Status />