@candourorg/ui

Candour Component Library

Introduction

The Candour Component Library is a collection of reusable React components designed to simplify the development of user interfaces. This library provides a set of well-crafted components that can be easily integrated into your projects, ensuring a consistent look and feel while saving development time. Whether you're building a small application or a large-scale project, these components are flexible, customizable, and ready to use.

Key Features

• Customizable Components: Each component comes with a variety of props for customization, allowing you to tailor styles and behavior to your needs.
• Accessibility: Designed with accessibility in mind to ensure your applications are usable by everyone.
• Lightweight: The library is lightweight and optimized for performance, ensuring a smooth user experience.
• Responsive Design: Components are built to be responsive, adapting to different screen sizes seamlessly.

Installation

To install the library, you can use npm or yarn:

npm install @candourorg/ui

or

yarn add @candourorg/ui

or

bun install @candourorg/ui

Button Component

Prop	Type	Default	Description
variant	button | submit | reset	-	Button variant style.
padding	string	-	Button padding style.
onClick	() => void	-	Click event handler.
children	ReactNode	-	Content inside the button.
disabled	boolean	false	Disables the button.
plusIcon	boolean	false	Shows plus icon.
userIcon	boolean	false	Shows user icon.
arrowLeft	boolean	false	Shows left arrow icon.
arrowDown	boolean	false	Shows left arrow icon.
className	string	-	Additional class names.
deleteIcon	boolean	false	Shows delete icon.
arrowRight	boolean	false	Shows right arrow icon.
colorscheme	string	-	Button color scheme.
loadingStyle	string	-	Loading indicator style.
isSubmitting	boolean	false	Indicates submitting state.
settingsIcon	boolean	false	Shows settings icon.
fileShieldIcon	boolean	false	Shows file shield icon.
plusIconPosition	'left' | 'right'	'right'	Position of plus icon.

Usage

<Button
  type="submit"
  variant="solid"
  disabled
  plusIcon
  className="submitButton"
  onClick={() => console.log('Button clicked!')}
>
  Submit
</Button>

---

Dropdown Component

DropdownItem

Prop	Type	Default	Description
children	ReactNode	-	Dropdown item to display.
itemKey	string	-	Unique key for the item.
padding	string	-	Padding style for the item.
font	string	-	Font style for the item.
color	string	-	Text color for the item.

DropDownMenu

Prop	Type	Default	Description
children	ReactNode	-	Dropdown items to display.
bg	string	-	Background color for the menu.
padding	string	-	Padding style for the menu.
size	string	-	Size of the menu.
radius	string	-	border radius of the DropDown.
shadow	string	-	box shadow of the DropDown.
onAction	(key: string) => void	-	Called when an item is selected.

DropdownTrigger

Prop	Type	Default	Description
children	ReactNode	-	Content inside the trigger.

DropdownWrapper

Prop	Type	Default	Description
children	ReactNode	-	Trigger and menu items.
position	string	-	Positioning of the menu.
otherProps	object	-	Additional props for context.

Usage

<DropdownWrapper>
  <DropdownTrigger>
    <Button type="button" variant="solid" onClick={() => {}}>
      Trigger Drop Down
    </Button>
  </DropdownTrigger>

  <DropDownMenu
    onAction={handleDropDownAction}
    size="lg"
    radius="md"
    shadow="xl"
  >
    <DropdownItem itemKey="new" text="New file" />
    <DropdownItem itemKey="old" text="Old file" />
  </DropDownMenu>
</DropdownWrapper>

---

Popover Component

Popover

Prop	Type	Default	Description
popoverId	string	-	Unique ID for the popover.
children	ReactNode	-	Content inside the popover.
closeOnBackdropClick	boolean	true	Closes popover on backdrop click.
position	string	-	Positioning of the popover.

PopoverTrigger

Prop	Type	Default	Description
children	ReactNode	-	Content inside the trigger.

PopoverContent

Prop	Type	Default	Description
children	ReactNode	-	Content inside the popover.
bg	string	-	Background color for the content.
padding	string	-	Padding style for the content.
size	string	-	Size of the content.

Usage

<Popover>
  <PopoverTrigger>
    <button>Open Popover</button>
  </PopoverTrigger>
  <PopoverContent variant="solid" position="bottom">
    <p>Popover content (bottom)!</p>
  </PopoverContent>
</Popover>

Modal

Prop	Type	Default	Description
modalId	string	-	Unique ID for the modal.
children	ReactNode	-	Content inside the modal.
closeOnBackdropClick	boolean	true	Closes modal on backdrop click.

Usage

<Modal modalId="modalId" closeOnBackdropClick>
  <div>This is the modal content</div>
</Modal>

Toast

Prop Name	Type	Default	Description
action	string	-	Title or label of the toast.
toastId	string	-	Unique ID for the toast.
message	string	-	Content displayed in the toast.
closeButton	boolean	false	Shows a close button if true.
duration	number	5000	Time in milliseconds before the toast automatically closes.
position	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	'top-right'	Defines the corner of the screen where toasts appear.
variant	'default' | 'success' | 'error' | 'info' | 'warning' | 'promise'	'default'	Sets the visual style of the toast based on its type.

Usage

<Toast
  action="Success"
  toastId="toastId"
  message="Item deleted successfully."
  variant="info"
  position="top-right"
  closeButton
/>

Toast Container

Usage

Place the ToastContainer at the root of your app or in a specific component

<ToastContainer />

ToggleTheme

-

<ToggleTheme />

Filter Component

Filter

Prop	Type	Default	Description
children	ReactNode	-	The trigger and menu items of the filter button.
variant	'solid' or 'outline'	'outline'	Style variant of the filter button.

FilterTrigger

Prop	Type	Default	Description
label	string	-	The text label for the filter button.
arrowDown	boolean	false	If true, shows an arrow-down icon in the button.
filterIcon	boolean	false	If true, displays a filter icon in the button.
iconPosition	'left' or 'right'	'right'	Determines the position of the icon in the button.
className	string	-	Additional class names for custom styling.
disabled	boolean	false	If true, the button is disabled.

FilterMenu

Prop	Type	Default	Description
children	ReactNode	-	List of filter items to display in the menu.
onSelectionChange	(value: string) => void	-	Callback when a filter item is selected.
selectedKey	string	-	Key of the currently selected filter item.
className	string	-	Additional class names for custom styling.

FilterItem

Prop	Type	Default	Description
value	string	-	The value that represents the filter item.
children	ReactNode	-	The content to be displayed in the item.

Usage

<Filter>
  <FilterTrigger
    label="Filter"
    arrowDown
    iconPosition="right"
    variant="solid"
  />

  <FilterMenu onSelectionChange={handleFilterChange} selectedKey={selectedKey}>
    <FilterItem value="new">New Item</FilterItem>
    <FilterItem value="popular">Popular Item</FilterItem>
    <FilterItem value="old">Old Item</FilterItem>
  </FilterMenu>
</Filter>

Sort Component

Sort

Prop	Type	Default	Description
children	ReactNode	-	The trigger and menu items of the sort component.
onChange	(value: string) => void	-	Callback function triggered when a sort item is selected.

SortTrigger

Prop	Type	Default	Description
label	string	-	The text label for the sort button.
arrowDown	boolean	false	If true, shows an arrow-down icon in the button.
sortIcon	boolean	false	If true, displays a sort icon in the button.
className	string	-	Additional class names for custom styling.
disabled	boolean	false	If true, the button is disabled.

SortMenu

Prop	Type	Default	Description
children	ReactNode	-	List of sort items to display in the menu.
onSelectionChange	(value: string) => void	-	Callback when a sort item is selected.
selectedKey	string	-	Key of the currently selected sort item.
className	string	-	Additional class names for custom styling.

SortItem

Prop	Type	Default	Description
value	string	-	The value that represents the sort item.
onClick	MouseEventHandler<HTMLLIElement>	-	Handler called when the item is clicked.
children	ReactNode	-	The content to be displayed in the item.

Usage

<Sort onChange={handleChange}>
  <SortTrigger sortIcon arrowDown label="Sort" />
  <SortMenu selectedKey={selected} onSelectionChange={handleChange}>
    {data.map((item) => (
      <SortItem value={item.value} key={item.label}>
        {item.label}
      </SortItem>
    ))}
  </SortMenu>
</Sort>

DatePicker Component

RegularDatePicker

The RegularDatePicker component is a flexible and customizable. It allows users to select a single date or a date range, with support for various configurations such as date format, display options, and accessibility features.

Features

• Supports both single-date and range selection.
• Customizable date format for display and input.
• Optional footer and shortcut options to improve usability.
• Min and Max date restrictions to ensure valid date selection.

Example Usage

Below are two examples demonstrating how to use the RegularDatePicker component in a React application: one in range mode and the other in single-date mode.

Example 1: Date Range Selection (Range Mode)

In this example, the RegularDatePicker allows users to select a range of dates. The useRange prop is set to true, and asSingle is set to false.

import React, { useState } from 'react';
import { RegularDatePicker } from '@candourorg/ui';

const DateRangePickerExample: React.FC = () => {
  const [value, setValue] = useState<DateRange>({
    startDate: null,
    endDate: null,
  });

  console.log(value);

  return (
    <RegularDatePicker
      useRange={true}
      label="Select a Date Range"
      placeholder="Select date range"
      asSingle={false}
      value={value}
      displayFormat={'DD/MM/YYYY'}
      onChange={(newValue: DateValueType) => setValue(newValue as DateRange)}
    />
  );
};

Example 2: Single-Date Selection (Single Mode)

In this example, the RegularDatePicker is configured for selecting a single date. The useRange prop is set to false, and asSingle is set to true.

import React, { useState } from 'react';
import { RegularDatePicker } from '@candourorg/ui';

const DateRangePickerExample: React.FC = () => {
  const [value, setValue] = useState<DateRange>({
    startDate: null,
    endDate: null,
  });

  console.log(value);

  return (
    <RegularDatePicker
      useRange={false}
      label="Select a Date Range"
      placeholder="Select date range"
      asSingle={true}
      value={value}
      displayFormat={'DD/MM/YYYY'}
      onChange={(newValue: DateValueType) => setValue(newValue as DateRange)}
    />
  );
};

Key Differences Between Range Mode and Single-Date Mode

The RegularDatePicker component can be used in two distinct modes: Range Mode and Single-Date Mode. Below is a comparison of the key differences between these modes:

Feature	Range Mode	Single-Date Mode
useRange Prop	Set to true to enable range selection.	Set to false to disable range selection.
asSingle Prop	Set to false to allow selecting a range of dates.	Set to true for selecting a single date.
Purpose	Allows selecting a start and end date, ideal for booking systems and event scheduling.	Allows selecting only one date, ideal for picking specific dates like birthdays.
Value Type	Managed as a DateRange object with startDate and endDate.	Managed as a single DateValueType.

By toggling the useRange and asSingle props, you can easily switch between range and single-date selection modes to fit your specific use case.

Regular Date Comprehensive Props Guide

Prop Name	Type	Required	Description
primaryColor	ColorKeys	No (Optional)	Primary color for styling the date picker.
value	DateValueType	Yes	The current value of the date picker.
onChange	(value: DateValueType, e?: HTMLInputElement | null | undefined) => void	Yes	Callback triggered when the date value changes.
useRange	boolean	No (Optional)	Whether to allow selecting a range of dates.
showFooter	boolean	No (Optional)	Whether to show footer actions in the date picker.
showShortcuts	boolean	No (Optional)	Whether to show shortcut options in the date picker.
configs	Configs	No (Optional)	Additional configuration options for the date picker.
asSingle	boolean	No (Optional)	Whether the picker operates in single-date selection mode.
placeholder	string	No (Optional)	Placeholder text displayed in the date picker input.
separator	string	No (Optional)	Separator text for date ranges.
startFrom	DateType	No (Optional)	Initial date or month to display when the picker opens.
i18n	string	No (Optional)	Internationalization key for locale settings.
disabled	boolean	No (Optional)	Whether the date picker is disabled.
classNames	ClassNamesTypeProp	No (Optional)	Custom class names for styling.
containerClassName	ClassNameType	No (Optional)	Class name for the container element.
popupClassName	ClassNameType	No (Optional)	Class name for the popup element.
inputClassName	ClassNameType	No (Optional)	Class name for the input field.
toggleClassName	ClassNameType	No (Optional)	Class name for the toggle button.
toggleIcon	(open: boolean) => ReactNode	No (Optional)	Custom toggle icon component.
inputId	string	No (Optional)	ID for the input field.
inputName	string	No (Optional)	Name attribute for the input field.
displayFormat	string	No (Optional)	Format in which the selected date(s) are displayed.
readOnly	boolean	No (Optional)	Whether the input field is read-only.
minDate	DateType	No (Optional)	Minimum selectable date.
maxDate	DateType	No (Optional)	Maximum selectable date.
dateLooking	DateLookingType	No (Optional)	Type of date selection behavior.
disabledDates	DateRangeType[]	No (Optional)	Array of date ranges to disable.
startWeekOn	WeekStringType	No (Optional)	The day of the week to start on (e.g., Sunday or Monday).
popoverDirection	PopoverDirectionType	No (Optional)	Direction in which the popover opens (e.g., top, bottom).
required	boolean	No (Optional)	Whether the date picker is required.

FormikDatePicker

FormikDatePicker is a React component designed for use with Formik to handle single-date input fields in forms. It supports selecting only one date.

---

Key Features:

• Single-Date Selection: For selecting one date.
• Formik Integration: Seamlessly works with Formik for form state and validation.
• Customizable: Easily configure label, error messages, and more.

Example Usage

The following example demonstrates how to use FormikDatePicker with Formik, including form validation using Yup.

import { Button, FormikDatePicker } from '@candourorg/ui';

const DatePickerFormik: React.FC = () => {
  const validationSchema = Yup.object().shape({
    startDate: Yup.string().required('Start Date is required').nullable(),
  });

  const companyTaxFormvalues = {
    startDate: '',
  };

  return (
    <Formik
      initialValues={companyTaxFormvalues}
      validationSchema={validationSchema}
      onSubmit={(values) => {
        console.log(values);
      }}
    >
      {(formikProps: FormikProps<any>) => {
        const { values, errors } = formikProps;

        return (
          <Form className="flex flex-col h-[calc(100vh-48px)]">
            <div className="flex items-center gap-5">
              <div className="grow">
                <Field
                  type="date"
                  id="startDate"
                  name="startDate"
                  label="Start Date"
                  placeholder="Choose a date"
                  value={values.startDate}
                  component={FormikDatePicker}
                  showError={!!errors.startDate}
                  errorMessage={errors.startDate}
                  form={formikProps}
                />
              </div>
            </div>
            <div className="flex-none">
              <Button
                type="submit"
                disabled={false}
                isSubmitting={false}
                className="w-full mt-3"
              >
                Submit
              </Button>
            </div>
          </Form>
        );
      }}
    </Formik>
  );
};

Formik Date Picker Comprehensive Props Guide

Prop Name	Type	Required	Description
value	Date	Yes	The current value of the date picker.
label	string	Yes	Label text for the date picker.
disabled	boolean	Yes	Whether the date picker is disabled.
showError	boolean	Yes	Controls the visibility of error messages.
errorMessage	string	Yes	Error message displayed when validation fails.
placeholder	string	No (Optional)	Placeholder text displayed in the date picker.
showFooter	boolean	No (Optional)	Whether to show footer actions in the date picker.
showShortcuts	boolean	No (Optional)	Whether to show shortcut options in the date picker.
displayFormat	string	No (Optional)	The format in which the selected date is displayed.
minDate	DateValueType	No (Optional)	Minimum selectable date.