@oliasoft-open-source/react-ui-library v4.4.4

React UI Library

Description

The React UI Library by Oliasoft is a versatile set of React UI components designed for building modern web applications. It offers a comprehensive suite of layout, navigation, and control components that are flexible and configurable. With detailed examples available in Storybook, developers can easily understand how to implement and customize components for their needs. This library is open-source and can be freely used and modified under the MIT License.

Installation

To install the React UI Library, you can use either npm or yarn as follows:

Using npm:

npm install @oliasoft-open-source/react-ui-library

Using yarn:

yarn add @oliasoft-open-source/react-ui-library

Quick Start: React and Vite

To quickly start a new project using the React UI Library with Vite, you can use the create-vite tool, which sets up everything for you in a few simple steps:

1. Create a New Vite Project: Use the create-vite command to scaffold a new React project. Run:

   npm create vite@latest my-new-project -- --template react

   Or with yarn

   yarn create vite my-new-project --template react

2. Navigate into the Project Directory:

   cd my-new-project

3. Install React UI Library: Add the React UI Library to your project:

   npm install @oliasoft-open-source/react-ui-library

   Or with yarn

    yarn add @oliasoft-open-source/react-ui-library

4. Modify the Sample Page: Open the src/App.jsx file and import a component from the React UI Library to use it:

   import React from 'react';
   import { Text } from '@oliasoft-open-source/react-ui-library';
   
   function App() {
     return (
       <div className="App">
         <Text>Hello World!</Text>
       </div>
     );
   }
   
   export default App;

5. Start the Development Server: Begin development by starting the Vite server:

   npm run dev

   Or with yarn

    yarn dev

Components

• Accordion
• AccordionWithDefaultToggle
• Actions
• Badge
• Breadcrumb
• Button
• ButtonGroup
• Card
• CheckBox
• Column
• Divider
• Dialog
• Drawer
• Empty
• FileInput & readFile
• Field
• Flex
• FormRow
• Grid
• Icon
• InputGroup
• InputGroupAddon
• HelpIcon
• Heading
• Input
• Label
• List
• ListHeading
• ListSubheading
• Loader
• Menu
• Message
• Modal
• OptionDropdown
• Page
• Pagination
• Popover
• Portal
• PrintHeader
• ProgressBar
• RadioButton
• RichTextInput
• NativeSelect
• Row
• Select
• SideBar
• Slider
• Spacer
• Spinner
• Table
• Tabs
• Text
• TextLink
• TextArea
• toast
• Toggle
• Tooltip
• TopBar
• PopConfirm
• Tree
• NumberInput
• UnitInput

Storybook

To see live examples and demos of the components, please visit our Storybook.

License

This project is open-source and available under the MIT License.

Questions or Issues?

If you have any questions or encounter any issues, please open an issue on the issues page of the repository.

Components Details

Accordion Component

The Accordion component provides a versatile way to toggle visibility of content. It can be expanded to show content or collapsed to hide content, with additional options for styling and behavior customization.

Properties

Usage Example

<Accordion
  heading="Section 1"
  expanded
  bordered
  onClick={() => console.log("Accordion clicked")}
>
  Content goes here
</Accordion>

AccordionWithDefaultToggle

An enhanced accordion component that includes a default toggle feature, allowing for more interactive and user-driven content display. It extends the basic functionality of an accordion by offering a built-in toggle option with customizable label and behavior.

Props

Usage Example

<AccordionWithDefaultToggle
  heading="Section 1"
  toggleLabel="Enable Section"
  onClickDefaultToggle={(evt) => console.log(evt.target.checked)}
  expanded
  defaultEnabled
  padding
>
  {/* Content here */}
</AccordionWithDefaultToggle>

Actions

The Actions component is designed to display a set of actions or options. It supports primary actions, subactions, icons, tooltips, and can conditionally hide or disable actions. Ideal for implementing interactive lists, toolbars, or context menus within your application.

Properties

IAction Properties

Usage Example

<Actions
  actions={[
    {
      label: 'Action 1',
      onClick: () => console.log('Action 1 clicked'),
      primary: true,
    },
    {
      label: 'Action 2',
      onClick: () => console.log('Action 2 clicked'),
      disabled: true,
    },
    {
      label: 'Action 3',
      onClick: () => console.log('Action 3 clicked'),
      tooltip: 'This is a tooltip for Action 3',
    },
  ]}
/>

Badge

The Badge component is used to display a small badge, often used to show a count or to label an item with a short piece of text. This component can be customized with color, size, and optional dot mode for notifications or status indicators.

Properties

Usage Example

<Badge
  color="red"
  title="New"
  dot
  margin="0 8px"
  small
>
  {/* Children here, if any */}
</Badge>

Breadcrumb Component

The Breadcrumb component displays a navigation path, typically used to show the user's location within a hierarchical structure.

Props:

ILinkProps Interface:

This interface defines the properties for each breadcrumb link.

Usage Example:

<Breadcrumb
  links={[
    { label: 'Home', url: '/' },
    { label: 'Products', url: '/products' },
    { label: 'Current Product', active: true },
  ]}
/>

Button

The Button component is a versatile interface element that supports various styles and states, including active, basic, colored, disabled, and loading states. It's suitable for a wide range of actions within an application, from form submissions to interactive commands.

Props

Usage Example

<Button
  label="Click Me"
  onClick={() => console.log('Button clicked')}
  colored="blue"
  small
/>

ButtonGroup

The ButtonGroup component allows for the grouping of button-like elements, making it useful for presenting a selection of options or actions together. This component supports customization in terms of appearance, selection handling, and more, making it versatile for various UI scenarios.

IButtonGroupProps

IBtnGroupItemProps

Usage Example

<ButtonGroup
  items={[
    { label: 'Button 1', value: '1' },
    { label: 'Button 2', value: '2', disabled: true },
    { label: 'Button 3', value: '3' }
  ]}
  onSelected={(selectedValue) => console.log(selectedValue)}
/>

Card

Props

Usage Example

<Card heading="Card Title" raised>
  <p>This is some content within a card.</p>
</Card>

CheckBox

The CheckBox component is used to create a checkbox input field, often utilized for options that can be toggled between two states, such as true/false or yes/no. This component supports various customizations including label display, size adjustments, and integrated help text.

Props

Usage Example

<CheckBox
  label="Accept Terms"
  name="termsAccepted"
  checked={this.state.accepted}
  onChange={e => this.setState({ accepted: e.target.checked })}
/>

Column

The Column component is a layout tool designed for creating structured, flexible column-based layouts within your application. It supports a wide range of customization options, including background color, border control, padding, and responsive width adjustments, making it an essential element for responsive design.

Props

Usage Example

<Column
  background="lightgrey"
  borderLeft="1px solid black"
  padding="20px"
  width={100}
  widthMobile={50}
>
  {/* Column Content Here */}
</Column>

Divider

The Divider component visually separates content within your layout. It's customizable with respect to margin, color, and alignment, making it versatile for various design needs. It can be particularly useful in forms, lists, or between sections of content to provide a clear visual distinction.

Props

Usage Example

<Divider align="center" color="grey" margin="20px">
  <Text>OR</Text>
</Divider>

Dialog

The Dialog component encapsulates a dialog box or modal's structure and behavior, providing a flexible way to display content in a floating layer above the app's main UI. This component supports a variety of content and layouts, including headers, footers, and customizable padding, making it ideal for confirmations, information dialogs, and more complex interactions.

Props

Usage Example

<Dialog
  dialog={{
    heading: "Dialog Title",
    content: "This is the content of the dialog.",
    footer: <button onClick={() => console.log('Closing dialog')}>Close</button>,
    width: 400,
    scroll: true,
    onClose: () => console.log('Dialog closed'),
  }}
/>

Drawer

The Drawer component is a flexible and customizable sidebar or navigation drawer that slides in from the side of your application. It supports both left and right placement, fixed positioning, and the inclusion of tabs for additional organization. The drawer can be triggered to open or close programmatically, making it adaptable for various user interactions.

Props

Usage Example

<Drawer
  open={true}
  right
  width="250px"
  onClose={() => console.log("Drawer closed")}
>
  {/* Content here */}
</Drawer>

Empty

The Empty component is a useful UI element for displaying a state where there is no data or content available. It can be customized with specific dimensions and text, making it adaptable to various scenarios where you might need to inform users that a section or area is intentionally empty.

Props

Usage Example

<Empty
  width={300}
  height={200}
  text="No items found."
>
  <Button>Refresh</Button>
</Empty>

FileInput

The FileInput component allows users to select files from their device storage. It supports single and multiple file selections, customizable via props. This component is ideal for forms requiring file uploads, offering options for file type acceptance, loading states, and accessibility features.

Props

Usage Example

<FileInput
  label="Upload Document"
  accept=".pdf"
  multi
  onChange={(evt) => console.log(evt.target.files)}
/>

Field

The Field component serves as a container for form elements, providing a structured layout for labels, input fields, help text, and additional features like lock icons or information tooltips.

Props

Usage Example

<Field
  label="Username"
  helpText="Choose a unique username"
  info="Your username must be at least 6 characters long."
>
  <Input placeholder="Enter your username" />
</Field>

Flex

The Flex component enables flexible layout arrangements by providing properties to control the alignment, direction, and spacing of its children elements.

Props

Usage Example

<Flex alignItems="center" justifyContent="space-between" direction="row" gap={10}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Flex>

FormRow

The FormRow component is used to group form elements together in a row layout.

Props

Usage Example

<FormRow>
  <Input label="Username" />
  <Button label="Submit" onClick={handleSubmit} />
</FormRow>

Grid

The Grid component allows you to create a grid layout with specified rows and columns.

Props

Usage Example

<Grid rows="auto" columns="repeat(3, 1fr)" gap={20}>
  <GridItem>Item 1</GridItem>
  <GridItem>Item 2</GridItem>
  <GridItem>Item 3</GridItem>
</Grid>

Icon

The Icon component is a wrapper used to render various types of icons within your application.

Props

Usage Example

<Icon icon="search" color="blue" size={24} />

In this example, the Icon component renders an icon with the name "search", colored blue, and sized at 24 pixels.

• The icon prop accepts various formats such as string names, React components, or SVG elements.
• If using a string name, it's recommended to use icon libraries like Font Awesome or Material Icons.
• When providing a custom SVG, ensure it's properly formatted and compatible with React's rendering.
• Setting the clickable prop to true adds cursor pointer and hover effects to the icon.

<Icon icon={<CustomIcon />} clickable onClick={handleIconClick} />

InputGroup

The InputGroup component is used to group together multiple input elements or components.

Props

Usage Example

<InputGroup>
  <Input placeholder="Username" />
  <Button>Search</Button>
</InputGroup>

InputGroupAddon

The InputGroupAddon component is used to add additional content or components to an InputGroup.

Props

Usage Example

<InputGroup>
  <InputGroupAddon>$</InputGroupAddon>
  <Input placeholder="Amount" />
</InputGroup>

HelpIcon

The HelpIcon component provides an icon with optional tooltip text to offer assistance or additional information.

Props

Usage Example

<HelpIcon text="Click here for more information" />

Heading

The Heading component renders a heading element with optional features such as help text and an icon.

Props

Usage Example

<Heading>Page Title</Heading>

<Heading
  top={true}
  onClick={() => console.log('Heading clicked')}
  helpText="This is the main title of the page"
  onClickHelp={() => console.log('Help text clicked')}
  icon={<QuestionCircleOutlined />}
  libraryIcon={{ onClick: () => console.log('Library icon clicked'), tooltip: 'More info' }}
  marginBottom="10px"
>
  Page Title
</Heading>

Input

The Input component provides an input field for users to enter data. It supports various features such as error and warning messages, tooltips, and custom event handlers.

Props

Usage Example

<Input
  type="text"
  placeholder="Enter your name"
  value={name}
  onChange={(e) => setName(e.target.value)}
  error={nameError}
  tooltip="Please enter your full name"
  disabled={isDisabled}
/>

<Input
  type="number"
  placeholder="Enter your age"
  value={age}
  onChange={(e) => setAge(e.target.value)}
  warning={ageWarning}
/>

Label

The Label component represents a label or caption associated with an input field or other form elements. It can include optional elements such as help text, lock icons, and library icons.

Props

Lock Props:

Usage Example

<Label
  label="Username"
  helpText="Enter your username"
  onClickHelp={() => console.log('Help clicked')}
  lock={{
    visible: true,
    active: false,
    onClick: () => console.log('Lock clicked'),
    tooltip: 'Locked',
  }}
  libraryIcon={{
    onClick: () => console.log('Library icon clicked'),
    tooltip: 'Open library',
  }}
/>

List

The List component renders a list of data items with various customization options such as borders, expanding items, and draggable rows.

Props

Scroll Details:

Usage Example

<List
  list={myData}
  bordered
  expanding
  draggable
  stickyHeader
  marginBottom={20}
  height={300}
  testId="my-list"
  scrollDetails={{
    scrollable: true,
    hideScrollbar: true,
    triggerScrollToActiveItem: true,
    infiniteScroll: true,
    limit: 10,
    infiniteScrollTarget: document.getElementById('list-container'),
  }}
/>

ListHeading

The ListHeading component represents the header of a list. It typically includes the name or title of the list and optional actions.

Props

Usage Example

<ListHeading
  name="My List"
  actions={[{ label: 'Add', onClick: handleAdd }, { label: 'Edit', onClick: handleEdit }]}
  toggleNarrow
  onToggleNarrow={handleToggleNarrow}
  stickyHeader
/>

ListSubheading

The ListSubheading component represents a subheading within a list. It is typically used to provide additional information or context for a group of items within the list.

Props

Usage Example

<ListSubheading item={{ label: 'Group A', count: 5 }} index={0} />

Loader

The Loader component renders a loading indicator, typically used to indicate that content is being fetched or processed.

Props

Usage Example

<Loader text="Loading..." cover />

Menu

The Menu component is used to render a menu with various options or sections.

Props