React Simple Widgets

React Simple Widgets is a collection of composable, customizable widgets to help accelerate your React app development. These widgets perform commonly needed tasks within your app such as dialogs, flash messages, lists and more.

To find out if this library is right for you, we've compiled the Storybook samples of all widgets in this library. Click here to test them out to seem if this library offers what you want before installing it in your project.

Supporting

React Simple Widgets is currently maintained solely by the owner and will always be free and open-source. However, if you find this library helpful to your projects and would like to support the development, you can do so via my Patreon account.

The funds would be used to get an active team of developers on the project and speed up updates. You are not obligated to this, but every support goes a long way to help bring you enterprise-grade tools and services.

If you love the library, consider leaving a star on the project page on Github.

Installing

Install the latest version of React Simple Widgets by running the following command:

yarn add --dev react-simple-widgets

Peer Dependencies

React Simple Widgets requires a few peer dependencies you must also have installed in your project. These are React, React DOM, React Router DOM and Formik. Install these by running the following command:

yarn add --dev react react-dom react-router-dom formik

CSS Dependencies

React Simple Widgets also depends on Bootstrap 5.2.1+ for base styling and Font Awesome 5.14.0+ for font icons. These must be included in the index.html of your project.

Global Style

From v6.7.0 onward, the global styles for the library must be imported at the start of your app

import ReactDOM from "react-dom";
import { RSWGlobalStyle } from "react-simple-widgets/dist/style";
import App from "./app";
/* Other imports */

const root = document.getElementById("root");

ReactDOM.createRoot(root).render(
  <React.StrictMode>
    <RSWGlobalStyle />
    <App/>
  </React.StrictMode>
);

Widgets

Here's a summary of the widgets in React Simple Widgets

• DialogProvider - Provides an easy-to-use dialog framework within your app. Dialogs are rendered over the rest of the app

• LocalStorageProvider - Provides a reactive wrapper for the local storage API and syncs changes to its state with the browser's local storage

• FlashProvider - Provides a flash message framework built on top of the DialogProvider framework

  ---

• FilePicker - A file picker widget which also supports drag-and-drop

• DatePicker - A date picker widget which allows selection of a single date in YYYY-MM-DD format

• MultiDatePicker - A date picker widget which allows selection of multiple dates in YYYY-MM-DD format

• MonthDatePicker - A date picker widget which allows selection of a single month in YYYY-MM-DD format

• TimePicker - A 12-hour time picker widget which allows selection of a single time in HH:mm format

  ---

• CustomField - A widget that allows custom components to be integrated with a Formik form

• FieldDecoration - A widget that provides input decoration for its child

• TextField - A simple string (<input/>) form widget

• TextAreaField - A simple text (<textarea/>) form widget

• TextEditorField - A WYSIWYG editor form field build on top of the Quill rich text editor

• PasswordField - A simple password (<input type="password"/>) form widget

• DropdownField - A simple drop down (<select/>) form widget

• CheckboxField - A simple checkbox (<input type="checkbox"/>) form widget

• SelectField - A select widget that allows a single selection from a list of options

• MultiSelectField - A select widget that allows multiple selections from a list of options

• FileField - A form widget for the uploading files built on top of FilePicker

• DateField - A form widget for selecting a single date built on top of DatePicker

• MultiDateField - A form widget for selecting multiple dates built on top of MultiDatePicker

• MonthDateField - A form widget for selecting a single date built on top of MonthDatePicker

• TimeField - A form widget for selecting a single time built on top of TimePicker

• TagField - A form widget for multi-tag input built on top of TagInput

  ---

• PopupMenu - A widget that revals a popup menu when a trigger element is clicked

• TableView - A widget that displays a list of items in a responsive tabular form

• Pagination - A widget which displays pagination navigation for a list of items. This is commonly used with TableView

• ObjectView - A widget that renders an object's data in a tabular form

• Loader - A widget that displays a rotating spinner icon to indicate some busy process

• BusyButton - A button widget that displays a loading indicator when its busy attribute is true

• ConfirmButton - A widget which displays a confirmation dialog for an action to be performed

• Breadcrumbs - A breadcrumb style navigation widget

• ActionBar - A widget that displays a row of spaced buttons or nothing if no children are specified

• InfiniteList - A widget that provides a load-more mechanism for an infinite list of items

• TagInput - A widget allows multiple tags to be entered into the text input using the Enter or Tab keys

Hooks

• useQueryParams - A hook that returns a object containing the URL search string parameters

• useCountdown - A hook which provides numeric countdown functionality

• useWindowBreakpoints - A hook which provides the window width category data according to Bootstrap's breakpoints

• useInfiniteList - A hook which manages the state of an infinite list. Used with InfiniteList to provide a load-more mechanism for said infinite list

Utilities

• debounce - Calls a function after a specified delay after a caller has stopped calling it

Theming

The colors used by the widgets are controlled by CSS variables and you can customize them to suit your application's theme

| CSS variable | Description | Default value | | --------------------------- | -------------------------------------------------------- | ------------- | | --rsw-label-color | Controls the label color of field decorator | #777777 | | --rsw-error-color | Controls the error color of components indicating errors | #ff5555 | | --rsw-primary-color | Controls the primary color used by all widgets | #402897 | | --rsw-primary-color-light | Controls the lighter shade of the primary color | #40289722 | | --rsw-secondary-color | Controls the secondary color used by all widgets | #b3b3b3 | | --rsw-transition-duration | Controls the duration of transitions used by all widgets | 0.15s |

The following variables are widget specific

| CSS variable | Description | Default value | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | --rsw-flash-view-error-theme-color | Controls the theme color of error flash message dialogs created by the FlashProvider widget | #ff5555 | | --rsw-flash-view-warning-theme-color | Controls the theme color of warning flash message dialogs created by the FlashProvider widget | #ffdd55 | | --rsw-flash-view-info-theme-color | Controls the theme color of information flash message dialogs created by the FlashProvider widget | #55ddff | | --rsw-flash-view-success-theme-color | Controls the theme color of success flash message dialogs created by the FlashProvider widget | #6cd924 | | --rsw-popup-menu-scrim-bg-color | Controls the background color of the scrim that appears when a PopupMenu is revealed | #00000004 |

Running Storybook Samples Locally

This library is built with Storybook and each widget has its own set of stories demonstrating use cases of the widget. When executed, Storybook will open a web page containing all the stories for you to interact with.

To execute the storybook, follow these steps:

1. Clone the project from Github
2. Run yarn install to install the project dependencies
3. Run yarn storybook

Maintainers

• Kwame Opare Asiedu

Change Log

View change log