npm package: @symply.io/basic-components
Description: Basic and reusable components for all frontend of Symply apps
Author: Janden Ma
Latest version: 1.8.2

<h1 align="center">Symply Basic Components</h1>

<p align="center">Basic and reusable components for all frontend of Symply apps.</p>

<p align="center">Built with <a href="https://mui.com/">Material UI v5</a>.</p>

---

<h2>Quick Guide</h2>

- [Installation](#installation)
- [License](#license)
- [Components](#components)
  - [AlertDialog](#alertdialog)
  - [Autocomplete](#autocomplete)
  - [AutocompleteWithFilter](#autocompletewithfilter)
  - [BasicModal](#basicmodal)
  - [BreadCrumbs](#breadcrumbs)
  - [CheckBox](#checkbox)
  - [CheckBoxGroup](#checkboxgroup)
  - [CliickableFabButton](#clickablefabbutton)
  - [Copyright](#copyright)
  - [DataTable](#datatable)
  - [DateInput](#dateinput)
    - [FullDateInput](#fulldateinput)
    - [MonthDayInput](#monthdayinput)
    - [MonthYearInput](#monthyearinput)
  - [DigitInput](#digitinput)
  - [FeinInput](#feininput)
  - [FormRadioGroup](#formradiogroup)
  - [FormSelector](#formselector)
  - [HelpCaption](#helpcaption)
  - [LoadingModal](#loadingmodal)
  - [MenuButtonGroup](#menubuttongroup)
  - [NumberInput](#numberinput)
  - [PasswordInput](#passwordinput)
  - [PhoneNumberInput](#phonenumberinput)
  - [Sidebar](#sidebar)
  - [SocialInput](#socialinput)
  - [TabGroup](#tabgroup)
  - [TablePagination](#tablepagination)
  - [TextInput](#textinput)
  - [ToastPrompt](#toastprompt)
  - [VideoPlayerModal](#videoplayermodal)
  - [VirtualDataTable](#virtualdatatable)
- [Changelog](#changelog)



<h2>Installation</h2>

It is available as an [npm package](https://www.npmjs.com/package/@symply.io/basic-components).

```shell
// with npm
npm install @symply.io/basic-components

// with yarn
yarn add @symply.io/basic-components
```



<h2>License</h2>

This project is licensed under the terms of the [MIT license](https://github.com/baseline-software/symply-basic-components/blob/main/LICENSE).



<h2>Common Properties</h2>

All components include these 2 properties to customize the theme

| Name           | Type                   | Default | Required | Description                   |
| -------------- | ---------------------- | ------- | -------- | ----------------------------- |
| primaryColor   | CSSProperties["color"] |         | false    | Primary color for the theme   |
| secondaryColor | CSSProperties["color"] |         | false    | Secondary color for the theme |



<h2>Components</h2>

<h3>AlertDialog</h3>

Diglog component for alerts or confirmations.

<h5>Import</h5>

```typescript
import { AlertDialog } from '@symply.io/basic-components/';
// or 
import AlertDialog from '@symply.io/basic-components/AlertDialog'; 
```

<h5>Props</h5>

| Name          | Type                                          | Default | Required | Description                                                  |
| ------------- | --------------------------------------------- | ------- | -------- | ------------------------------------------------------------ |
| children      | node                                          |         | true     | Dialog content.                                              |
| DialogButtons | element                                       |         | false    | Customized dialog action buttons.                            |
| maxWidth      | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| false | 'md'    | false    | Determine the max-width of the dialog. The dialog width grows with the size of the screen. Set to `false` to disable `maxWidth`. |
| onClose       | func                                          |         | true     | Callback fired when the component requests to be closed.<br />**Signature:**<br/>`function() => void` |
| open          | bool                                          | false   | true     | If `true`, the component is shown.                           |
| title         | string                                        | 'Info'  | false    | Dialog title                                                 |



<h3>Autocomplete</h3>

A normal text input enhanced by a panel of suggested options.

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { Autocomplete } from '@symply.io/basic-components/';
// or 
import Autocomplete from '@symply.io/basic-components/Autocomplete'; 
```

<h5>Option Props (IOption)</h5>

| Name   | Type             | Default | Required | Description                |
| ------ | ---------------- | ------- | -------- | -------------------------- |
| label  | string           |         | true     | Option label.              |
| value  | string \| number |         | false    | Option valie.              |
| [name] | unknown          |         | false    | Customized option property |

<h5>Props</h5>

| Name      | Type                   | Default | Required | Description                                                  |
| --------- | ---------------------- | ------- | -------- | ------------------------------------------------------------ |
| limitTags | number                 | -1      | false    | The maximum number of tags that will be visible when not focused. Set `-1` to disable the limit. |
| multiple  | bool                   | false   | false    | If `true`, `value` must be an array and the menu will support multiple selections. |
| onChange  | func                   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: Array<IOption|string>|IOption|string|null) => void`<br/>*value:* The value of the `Input` element. |
| options   | Array<IOption\|string> |         | true     | Array of suggestion options.                                 |
| value     | string                 |         | true     | The value of the `Input` element.                            |



<h3>AutocompleteWithFilter</h3>

A normal text input enhanced by a panel of suggested options and filter.

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { AutocompleteWithFilter } from '@symply.io/basic-components/';
// or 
import AutocompleteWithFilter from '@symply.io/basic-components/AutocompleteWithFilter'; 
```

<h5>Option Props (IOption)</h5>

| Name         | Type             | Default | Required | Description                                |
| ------------ | ---------------- | ------- | -------- | ------------------------------------------ |
| hideCheckbox | boolean          |         | false    | If `true`, the checkbox won't be rendered. |
| label        | string           |         | true     | Option label.                              |
| value        | string \| number |         | false    | Option valie.                              |
| [name]       | unknown          |         | false    | Customized option property                 |

<h5>Props</h5>

| Name                 | Type                   | Default | Required | Description                                                  |
| -------------------- | ---------------------- | ------- | -------- | ------------------------------------------------------------ |
| disableCloseOnSelect | bool                   | false   | false    | If `true`, the popup won't close when a value is selected.   |
| limitTags            | number                 | -1      | false    | The maximum number of tags that will be visible when not focused. Set `-1` to disable the limit. |
| multiple             | bool                   | false   | false    | If `true`, `value` must be an array and the menu will support multiple selections. |
| onChange             | func                   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: Array<IOption|string>|IOption|string|null) => void`<br/>*value:* The value of the `Input` element. |
| options              | Array<IOption\|string> |         | true     | Array of suggestion options.                                 |
| value                | string                 |         | true     | The value of the `Input` element.                            |



<h3>BasicModal</h3>

Reusable modal component.

It is extended from `@mui/material/Dialog`, so it includes all properties of `@mui/material/Dialog`.

<h5>Import</h5>

```typescript
import { BasicModal } from '@symply.io/basic-components/';
// or 
import BasicModal from '@symply.io/basic-components/BasicModal'; 
```

<h5>Props</h5>

| Name                    | Type                                                         | Default             | Required | Description                                                  |
| ----------------------- | ------------------------------------------------------------ | ------------------- | -------- | ------------------------------------------------------------ |
| cancelButtonColor       | 'primary' \| 'secondary' \| 'success' \| 'error' \| 'info' \| 'warning' \| undefined | same as the `color` | false    | The color of the cancel button.                              |
| cancelText              | string                                                       | 'Cancel'            | false    | The text of the cancel button.                               |
| children                | node                                                         |                     | true     | The content of the component.                                |
| color                   | 'primary' \| 'secondary' \| 'success' \| 'error' \| 'info' \| 'warning' \| undefined | 'primary'           | false    | The main color of the component.                             |
| desc                    | string                                                       |                     | false    | Some descriptions you want to add, similar to a subtitle.    |
| disabled                | bool                                                         | false               | false    | If `true`, the submit button would be disabled.              |
| hideBottomButtons       | bool                                                         | false               | false    | If `true`, hide all action buttons at the bottom of the modal. |
| loading                 | bool                                                         | false               | false    | If `true`, the submit and cancel buttons would be disabled.  |
| maxWidth                | 'xs' \|'sm' \|'md' \|'lg' \|'xl'                             | 'sm'                | false    | Determine the max-width of the dialog. The dialog width grows with the size of the screen. Set to `false` to disable `maxWidth`. |
| noForm                  | bool                                                         | false               | False    | If `true`, put the content and action buttons out of a form element. |
| onClose                 | func                                                         |                     | true     | Callback fired when the cancel button requests to be clicked.<br />**Signature:**<br/>`function() => void` |
| onSubmit                | func                                                         |                     | true     | Callback fired when the submit button requests to be clicked.<br />**Signature:**<br/>`function() => void` |
| open                    | bool                                                         | false               | true     | If `true`, the component is shown.                           |
| ref                     | ref                                                          |                     | false    | You can get the form "onSubmit" function from the ref.       |
| scroll                  | 'body' \| 'paper'                                            | 'paper'             | false    | Determine the container for scrolling the dialog.            |
| submitButtonColor       | 'primary' \| 'secondary' \| 'success' \| 'error' \| 'info' \| 'warning' \| undefined | same as the `color` | false    | The color of the submit button.                              |
| submitText              | string                                                       | ‘Save’              | false    | The text of the submit button.                               |
| showTopRightCloseButton | bool                                                         | false               | false    | If `true`, show a close icon button at the top right of the modal. |
| title                   | string                                                       |                     | true     | The title of the component, to show at the top left.         |



<h3>BreadCrumbs</h3>

A list of links that help a user visualize a page's location within the hierarchical structure of a website, and allow navigation up to any of its "ancestors".

<h5>Import</h5>

```typescript
import { BreadCrumbs } from '@symply.io/basic-components/';
// or 
import BreadCrumbs from '@symply.io/basic-components/BreadCrumbs'; 
```

 <h5>Props</h5>

| Name   | Type                                    | Default | Required | Description               |
| ------ | --------------------------------------- | ------- | -------- | ------------------------- |
| routes | Array<{ href?: string; label: string }> |         | true     | All routes of "ancestors" |



<h3>CheckBox</h3>

Checkboxes allow the user to select one or more items from a set.

It is extended from `@mui/material/Checkbox`, so it includes all properties of `@mui/material/Checkbox`.

<h5>Import</h5>

```typescript
import { CheckBox } from '@symply.io/basic-components/';
// or 
import CheckBox from '@symply.io/basic-components/CheckBox'; 
```

<h5>Props</h5>

| Name     | Type                   | Default | Required | Description                                                  |
| -------- | ---------------------- | ------- | -------- | ------------------------------------------------------------ |
| label    | string \| ReactElement |         | true     | The label of the checkbox.                                   |
| onChange | func                   |         | true     | Callback fired when the `checkbox` value is changed.<br />**Signature:**<br/>`function(value: boolean) => void`<br/>*value:* The value of the `checkbox` element. |



<h3>CheckBoxGroup</h3>

Checkboxes allow the user to select one or more items from a set for a group.

It is extended from `@mui/material/FormGroup`, so it includes all properties of `@mui/material/FormGroup`.

<h5>Import</h5>

```typescript
import { CheckBoxGroup } from '@symply.io/basic-components/';
// or 
import CheckBoxGroup from '@symply.io/basic-components/CheckBoxGroup'; 
```

<h5>Props</h5>

| Name       | Type                   | Default | Required | Description                                                  |
| ---------- | ---------------------- | ------- | -------- | ------------------------------------------------------------ |
| Checkboxes | Array\<CheckBoxProps\> |         | true     | The array of checkboxes.<br />See the property of [CheckBox](#checkbox) |



<h3>ClickableFabButton</h3>

A fab button with icon and text

<h5>Import</h5>

```typescript
import { ClickableFabButton } from '@symply.io/basic-components/';
// or 
import ClickableFabButton from '@symply.io/basic-components/ClickableFabButton'; 
```

<h5>Props</h5>

| Name     | Type                                                         | Default   | Required | Description                                                  |
| -------- | ------------------------------------------------------------ | --------- | -------- | ------------------------------------------------------------ |
| color    | "primary" \|"secondary" \|"success" \|"error" \|"info" \|"warning" | "primary" | false    | The button color.                                            |
| disabled | bool                                                         | false     | false    | If `true`, the button would be disabled.                     |
| fabIcon  | ReactElement                                                 |           | true     | The icon element.                                            |
| onClick  | func                                                         |           | true     | The function for button clicking.<br />**Signature:**<br/>`function() => unknown` |
| text     | string                                                       |           | true     | The button text.                                             |



<h3>Copyright</h3>

A common component for rendering the copyright

<h5>Import</h5>

```typescript
import { Copyright } from '@symply.io/basic-components/';
// or 
import Copyright from '@symply.io/basic-components/Copyright'; 
```

<h5>Props</h5>

| Name                   | Type   | Default              | Required | Description                                              |
| ---------------------- | ------ | -------------------- | -------- | -------------------------------------------------------- |
| allRightsReservedLabel | string | All Rights Reserved. | false    | The customized label for "All Rights Reserved".          |
| showAllRightsReserved  | bool   | false                | false    | If `true` , the "All Rights Reserved" will be displayed. |
| ownerHref              | string |                      | false    | The href ot the owner.                                   |
| ownerLabel             | string | Symply Software Inc  | false    | The owner of the copyright.                              |
| year                   | string | current year         | false    | The year of the copyright.                               |



<h3>DataTable</h3>

Reusable table component

<h5>Import</h5>

```tsx
import { DataTable, useDataTable } from '@symply.io/basic-components';
// or 
import DataTable, { useDataTable } from '@symply.io/basic-components/DataTable'; 
```

<h5>Column Props (ColumnProps)</h5>

| Name      | Type                          | Default | Required | Description                                                  |
| --------- | ----------------------------- | ------- | -------- | ------------------------------------------------------------ |
| accessor  | string                        |         | true     | The key of the column, it should be unique.                  |
| align     | "left" \|"center" \|"right"   |         | false    | The alignment of the column.                                 |
| Body      | ReactElement                  |         | true     | The component to render the column body cell.                |
| fixable   | "left" \| "right" \|undefined |         | false    | If not undefined, the column can be frozen. <br/>⚠️ It doesn't work with IE11. |
| Footer    | ReactElement                  |         | false    | The component to render the column footer cell.              |
| Header    | ReactElement                  |         | true     | The component to render the column header cell.              |
| headerTip | string                        |         | false    | The tip title text when the mouse is over the header.        |
| sortable  | bool                          |         | false    | If true, the column can be sortable.                         |
| width     | number                        |         | false    | The fixed width of cells.                                    |

<h5>Sorting Props</h5>

| Name     | Type                      | Default | Required | Description            |
| -------- | ------------------------- | ------- | -------- | ---------------------- |
| accessor | string                    |         | true     | The key of the column. |
| order    | "ASC" \| "DESC" \| "NONE" |         | true     | The sorting order.     |

<h5>Hook Props</h5>

| Name          | Type                       | Default | Required | Description                                                  |
| ------------- | -------------------------- | ------- | -------- | ------------------------------------------------------------ |
| columns       | Array\<ColumnProps\>       |         | true     | table columns                                                |
| data          | Array<{ [name]: unknown }> |         | true     | table data/rows                                              |
| disableSortBy | bool                       |         | false    | If true, the whole table can't be sortable.                  |
| initialState  | { sortBy?: SortingProps}   |         | false    | Set the initial states                                       |
| onSort        | func                       |         | false    | The function for sorting rows.<br />**Signature:**<br/>`function(props: SortingProps) => unknown` |

<h5>Hook Returns</h5>

| Name           | Type                          | Description                                                  |
| -------------- | ----------------------------- | ------------------------------------------------------------ |
| columns        | Array\<TableBodyCellProps\>   | The cells for the body.                                      |
| footers        | Array\<TableFooterCellProps>  | The cells for the footer.                                    |
| headers        | Array\<TableHeaderCellProps\> | The cells for the header.                                    |
| rows           | Array<RowProps\>              | The rows for the table.                                      |
| onResetSorting | func                          | An one-key function for resetting sorting to the initial state. |

<h5>Component Props</h5>

| Name                  | Type                          | Default    | Required | Description                                                  |
| --------------------- | ----------------------------- | ---------- | -------- | ------------------------------------------------------------ |
| columns               | Array\<TableBodyCellProps\>   |            | true     | The cells for the body. (from the hook)                      |
| dense                 | bool                          |            | false    | If `true` the table size/density would be tight.             |
| footers               | Array\<TableFooterCellProps>  | []         | false    | The cells for the footer. (from the hook)                    |
| footerBgColor         | CSSProperties["color"]        |            | false    | Customized footer background color.                          |
| footerTextColor       | CSSProperties["color"]        |            | false    | Customized footer text color.                                |
| headers               | Array\<TableHeaderCellProps\> |            | true     | The cells for the header. (from the hook)                    |
| headerBgColor         | CSSProperties["color"]        |            | false    | Customized header background color.                          |
| headerTextColor       | CSSProperties["color"]        |            | false    | Customized header text color.                                |
| noDataText            | string                        | 'No Data!' | false    | The text when no data rendered.                              |
| onContextMenu         | func                          |            | false    | The function for row right-clicking.<br />**Signature:**<br/>`function(event: MouseEvent, row: RowProps) => unknown` |
| onCustomizeRowBgColor | func                          |            | false    | The function for customizing the row background color.<br />**Signature:**<br/>`function(props: {row: RowProps, columns: Array\<ColumnProps\>}) => {normal?: HexColor;<br/>  hover?: HexColor;<br/>}` |
| onRowClick            | func                          |            | false    | The function for row clicking.<br />**Signature:**<br/>`function(row: RowProps) => unknown` |
| rows                  | Array<RowProps\>              |            | true     | The rows for the table. (from the hook)                      |



<h3>DateInput</h3>

<h4>FullDateInput</h4>

Input component for full date (MM/DD/YYYY)

<h5>Import</h5>

```typescript
import { FullDateInput } from '@symply.io/basic-components/';
// or 
import { FullDateInput } from '@symply.io/basic-components/DateInput'; 
// or 
import FullDateInput from '@symply.io/basic-components/DateInput/FullDateInput'; 
```

<h5>Props</h5>

| Name       | Type                          | Default | Required | Description                                                  |
| ---------- | ----------------------------- | ------- | -------- | ------------------------------------------------------------ |
| error      | boolean                       |         | false    | If `true`, the label is displayed in an error state.         |
| helperText | string                        |         | false    | The helper text content.                                     |
| margin     | 'dense' \| 'none' \| 'normal' | 'none'  | false    | If `dense` or `normal`, will adjust vertical spacing of this and contained components. |
| name       | string                        |         | false    | Name attribute of the `input` element.                       |
| onBlur     | func                          |         | false    | Callback fired when the `input` is blurred. Notice that the first argument (event) might be undefined. |
| onChange   | func                          |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onFocus    | func                          |         | false    | Callback fired when the `input` is focused.                  |
| onValidate | func                          |         | false    | Customized validation function.                              |
| value      | string                        |         | true     | The value of the `Input` element.                            |

<h4>MonthDayInput</h4>

Input component for month day (MM/DD)

<h5>Import</h5>

```typescript
import { MonthDayInput } from '@symply.io/basic-components/';
// or 
import { MonthDayInput } from '@symply.io/basic-components/DateInput'; 
// or 
import MonthDayInput from '@symply.io/basic-components/DateInput/MonthDayInput'; 
```

<h5>Props</h5>

| Name       | Type                          | Default | Required | Description                                                  |
| ---------- | ----------------------------- | ------- | -------- | ------------------------------------------------------------ |
| error      | boolean                       |         | false    | If `true`, the label is displayed in an error state.         |
| helperText | string                        |         | false    | The helper text content.                                     |
| margin     | 'dense' \| 'none' \| 'normal' | 'none'  | false    | If `dense` or `normal`, will adjust vertical spacing of this and contained components. |
| name       | string                        |         | false    | Name attribute of the `input` element.                       |
| onBlur     | func                          |         | false    | Callback fired when the `input` is blurred. Notice that the first argument (event) might be undefined. |
| onChange   | func                          |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onFocus    | func                          |         | false    | Callback fired when the `input` is focused.                  |
| onValidate | func                          |         | false    | Customized validation function.                              |
| value      | string                        |         | true     | The value of the `Input` element.                            |

<h4>MonthYearInput</h4>

Input component for month year (MM/YYYY)

<h5>Import</h5>

```typescript
import { MonthYearInput } from '@symply.io/basic-components/';
// or 
import { MonthYearInput } from '@symply.io/basic-components/DateInput'; 
// or 
import MonthYearInput from '@symply.io/basic-components/DateInput/MonthYearInput'; 
```

<h5>Props</h5>

| Name       | Type                          | Default | Required | Description                                                  |
| ---------- | ----------------------------- | ------- | -------- | ------------------------------------------------------------ |
| error      | boolean                       |         | false    | If `true`, the label is displayed in an error state.         |
| helperText | string                        |         | false    | The helper text content.                                     |
| margin     | 'dense' \| 'none' \| 'normal' | 'none'  | false    | If `dense` or `normal`, will adjust vertical spacing of this and contained components. |
| name       | string                        |         | false    | Name attribute of the `input` element.                       |
| onBlur     | func                          |         | false    | Callback fired when the `input` is blurred. Notice that the first argument (event) might be undefined. |
| onChange   | func                          |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onFocus    | func                          |         | false    | Callback fired when the `input` is focused.                  |
| onValidate | func                          |         | false    | Customized validation function.                              |
| value      | string                        |         | true     | The value of the `Input` element.                            |



<h3>DigitInput</h3>

Input component for digits. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { DigitInput } from '@symply.io/basic-components/';
// or 
import DigitInput from '@symply.io/basic-components/DigitInput'; 
```

<h5>Props</h5>

| Name         | Type      | Default | Required | Description                                                  |
| ------------ | --------- | ------- | -------- | ------------------------------------------------------------ |
| endAdornment | node      |         | false    | An end adornment element for the `Input` element.            |
| maxLength    | number    | 999     | false    | The max length of the `Input` element you can type in.       |
| minLength    | number    | 0       | false    | The min length of the `Input` element you should type in.    |
| onChange     | func      |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| value        | string    |         | true     | The value of the `Input` element.                            |
| tooltip      | ReactNode |         | false    | A tooltip for the `Input` element.                           |



<h3>FeinInput</h3>

Input component for FEIN. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { FeinInput } from '@symply.io/basic-components/';
// or 
import FeinInput from '@symply.io/basic-components/FeinInput'; 
```

<h5>Props</h5>

| Name       | Type   | Default | Required | Description                                                  |
| ---------- | ------ | ------- | -------- | ------------------------------------------------------------ |
| onChange   | func   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onValidate | func   |         | false    | Customized validation function.                              |
| value      | string |         | true     | The value of the `Input` element.                            |



<h3>FormRadioGroup</h3>

Radio Group allow the user to select one option from a set.

<h5>Import</h5>

```typescript
import { FormRadioGroup } from '@symply.io/basic-components/';
// or 
import FormRadioGroup from '@symply.io/basic-components/FormRadioGroup'; 
```

<h5>Radio Option Props</h5>

| Name     | Type                     | Default | Required | Description                              |
| -------- | ------------------------ | ------- | -------- | ---------------------------------------- |
| disabled | bool                     | false   | false    | If `true`, the opiton would be disabled. |
| label    | string                   |         | true     | The label of the option.                 |
| value    | string \| number \| bool |         | true     | The value of the option.                 |

<h5>Props</h5>

It is extended from `@mui/material/FormControl`, so it includes all properties of `@mui/material/FormControl`.

| Name                | Type                                  | Default | Required | Description                                                  |
| ------------------- | ------------------------------------- | ------- | -------- | ------------------------------------------------------------ |
| formLabel           | string                                |         | false    | The label of the `Radio` element.                            |
| helperText          | ReactNode                             |         | false    | A helper text for the `Radio` element.                       |
| onChange            | func                                  |         | true     | Callback fired when the `Radio` value is changed.<br />**Signature:**<br/>`function(value: string|number|boolean) => void`<br/>*value:* The value of the `Radio` element. |
| options             | Array\<IRadioOption\>                 |         | true     | The radio options. See the **Radio Option Props** above.     |
| radioLabelPlacement | 'top' \| 'bottom' \| 'start' \| 'end' | 'end'   | false    | The placement of the radio labe .                            |
| tooltip             | ReactNode \| string                   |         | false    | A tooltip for the `Radio` element.                           |
| value               | string \| number \| bool              |         | true     | The value of the `Radio` element.                            |



<h3>FormSelector</h3>

Selector components are used for collecting user provided information from a list of options.

<h5>Import</h5>

```typescript
// Simple Selector
import { SimpleSelector } from '@symply.io/basic-components/FormSelector';
// Multiple Selector 
import { MultipleSelector } from '@symply.io/basic-components/FormRadioGroup'; 
```

<h5>Selector Option Props</h5>

| Name     | Type                       | Default | Required | Description                              |
| -------- | -------------------------- | ------- | -------- | ---------------------------------------- |
| disabled | bool                       | false   | false    | If `true`, the opiton would be disabled. |
| label    | string                     |         | true     | The label of the option.                 |
| value    | T extends number \| string |         |          | The value of the option.                 |

<h5>Base Props</h5>

It is extended from `@mui/material/FormControl`, so it includes all properties of `@mui/material/FormControl`.

| Name           | Type                  | Default | Required | Description                                                 |
| -------------- | --------------------- | ------- | -------- | ----------------------------------------------------------- |
| helperText     | string                |         | false    | The helper text of the `Select` element.                    |
| label          | string                |         | false    | The label of `Select` element.                              |
| multiple       | bool                  | false   | false    | If `true`, you can select more than 1 option.               |
| options        | Array\<IRadioOption\> |         | true     | The radio options. See the **Selector Option Props** above. |
| showHelperText | bool                  | false   | false    | If `true`, show the helper text.                            |
| tooltip        | ReactNode             |         | false    | A tooltip for the `Select` element.                         |

<h5>Simple Selector Props</h5> Extended from the Base Props

| Name     | Type                       | Default | Required | Description                                                  |
| -------- | -------------------------- | ------- | -------- | ------------------------------------------------------------ |
| onChange | func                       |         | true     | Callback fired when the `Select` value is changed.<br />**Signature:**<br/>`function(value: string | number) => void`<br/>*value:* The value of the `Select` element. |
| value    | T extends number \| string |         | true     | The value of the `Select` element.                           |

<h5>Multiple Selector Props</h5> Extended from the Base Props

| Name           | Type                                | Default | Required | Description                                                  |
| -------------- | ----------------------------------- | ------- | -------- | ------------------------------------------------------------ |
| onChange       | func                                |         | true     | Callback fired when the `Select` value is changed.<br />**Signature:**<br/>`function(value: Array<number> | Array<string>) => void`<br/>*value:* The value of the `Select` element. |
| showCheckmarks | bool                                | false   | false    | If `true` the option will be shown with a checkbox.          |
| value          | Array\<T extends number \| string\> |         |          | The value of the `Select` element.                           |



<h3>HelpCaption</h3>

You can use it to add a hint/help paragraph.

<h5>Import</h5>

```typescript
import { HelpCaption } from '@symply.io/basic-components/';
// or 
import HelpCaption from '@symply.io/basic-components/HelpCaption';
```

<h5>Props</h5>

| Name        | Type                 | Default   | Required | Description                                                  |
| ----------- | -------------------- | --------- | -------- | ------------------------------------------------------------ |
| linkText    | string               |           | false    | The text of the help link.                                   |
| linkType    | 'WEBPAGE' \| 'VIDEO' | 'WEBPAGE' | false    | The type of the help link.                                   |
| linkUrl     | string               |           | false    | The url of the help link. If `undefined` then the help link would not be shown. |
| mainCaption | string               |           | true     | The primary text of the caption.                             |
| subCaption  | string               |           | false    | The secondary text of the caption.                           |



<h3>LoadingModal</h3>

A modal for loading.

<h5>Import</h5>

```typescript
import { LoadingModal } from '@symply.io/basic-components/';
// or 
import LoadingModal from '@symply.io/basic-components/LoadingModal';
```

<h5>Props</h5>

| Name        | Type                                                         | Default      | Required | Description                                                  |
| ----------- | ------------------------------------------------------------ | ------------ | -------- | ------------------------------------------------------------ |
| direction   | 'column' \| 'column-reverse' \| 'column' \| 'column-reverse' | 'column'     | false    | Defines the `flex-direction` style property. It is applied for all screen sizes. |
| open        | bool                                                         | false        | true     | If `true`, the component is shown.                           |
| percent     | number                                                       | 0            | false    | The percent value of the progress.                           |
| text        | string                                                       | 'Loading...' | false    | The prompt text of the component.                            |
| showProgess | boolean                                                      | false        | false    | If `true`, the percent of the progress is shown.             |



<h3>MenuButtonGroup</h3>

A button with menu options.

<h5>Import</h5>

```typescript
import { MenuButtonGroup } from '@symply.io/basic-components/';
// or 
import MenuButtonGroup from '@symply.io/basic-components/MenuButtonGroup';
```

<h5>Menu Button Props</h5>

| Name       | Type   | Default | Required | Description                                                  |
| ---------- | ------ | ------- | -------- | ------------------------------------------------------------ |
| buttonIcon | node   |         | false    | A start adornment of the button                              |
| buttonText | string |         | true     | The text of the menu button                                  |
| disabled   | bool   |         |          |                                                              |
| onClick    | func   |         | true     | Callback fired when the menu button click.<br />**Signature:**<br/>`function(event: MouseEvent) => void` |


<h5>Props</h5>

| Name       | Type                                                         | Default    | Required | Description                                        |
| ---------- | ------------------------------------------------------------ | ---------- | -------- | -------------------------------------------------- |
| color      | 'primary' \|'secondary' \|'success' \|'error' \|'info' \|'warning' | 'primary'  | false    | The main color of the component.                   |
| buttonText | string                                                       |            | true     | The text of the main button.                       |
| size       | 'small' \| 'medium' \| 'large'                               |            | false    | The size of the main button.                       |
| disabled   | bool                                                         |            | false    | If `true`, the button is disabled.                 |
| variant    | 'text' \|'contained' \|'outlined'                            | 'outlined' | false    | The variant of the main button.                    |
| buttons    | Array\<ButtonItemProps\>                                     |            | true     | Menu buttons. See the **Menu Button Props** above. |



<h3>NumberInput</h3>

Input component for Number. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { NumberInput } from '@symply.io/basic-components/';
// or 
import NumberInput from '@symply.io/basic-components/NumberInput'; 
```

<h5>Props</h5>

| Name        | Type      | Default     | Required | Description                                                  |
| ----------- | --------- | ----------- | -------- | ------------------------------------------------------------ |
| decimals    | number    | 0           | false    | The max length of decimals, if `0` then no limit.            |
| integerOnly | bool      |             | false    | If `true`, not allow to type a decimal value.                |
| maxValue    | number    | 2^53 − 1    | false    | The max value of the `Input` element you can type in.        |
| minValue    | number    | −(2^53 − 1) | false    | The min value of the `Input` element you should type in.     |
| onChange    | func      |             | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| tooltip     | ReactNode |             | false    | A tooltip for the `Input` element.                           |
| value       | string    |             | true     | The value of the `Input` element.                            |



<h3>PasswordInput</h3>

Input component for Password and Confirm Password. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
// Password
import Password from '@symply.io/basic-components/PasswordInput';
// Confirm Password 
import ConfirmPassword from '@symply.io/basic-components/ConfirmPasswordInput'; 
```

<h5>Password Props</h5>

| Name         | Type                                               | Default                                                      | Required | Description                                                  |
| ------------ | -------------------------------------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ |
| onChange     | func                                               |                                                              | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onValidate   | func                                               |                                                              | false    | Customized verify function when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| strategies   | { [key: string]: { label: string, regex: RegExp }} | {<br />uppercaseLetter: { label: "1 Uppercase Letter", regex: /[A-Z]+/ },<br />lowercaseLetter: { label: "1 Lowercase Letter", regex: /[a-z]+/ },<br />specialCharacter: { label: "1 Special Character", regex: /[!"#$%&'()*+,-./:;<=>?@[\]^_`{}~]/ },<br />number: { label: "1 Number", regex: /\d+/ },<br />minimum8: { label: "Minimum 8 characters", regex: /.{8,}/ }<br />} | false    | The strategies of the password                               |
| successColor | Color                                              | 'green'                                                      | false    | The color of component when success.                         |
| value        | string                                             |                                                              | true     | The password value.                                          |

<h5>Confirm Password Props</h5>

| Name     | Type   | Default | Required | Description                                                  |
| -------- | ------ | ------- | -------- | ------------------------------------------------------------ |
| onChange | func   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| password | string |         | true     | The password value                                           |
| value    | string |         | true     | The confirm password value.                                  |



<h3>PhoneNumberInput</h3>

Input component for US phone number. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { PhoneNumberInput } from '@symply.io/basic-components/';
// or 
import PhoneNumberInput from '@symply.io/basic-components/PhoneNumberInput'; 
```

<h5>Props</h5>

| Name         | Type   | Default | Required | Description                                                  |
| ------------ | ------ | ------- | -------- | ------------------------------------------------------------ |
| endAdornment | node   |         | false    | An end adornment element for the `Input` element.            |
| onChange     | func   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onValidate   | func   |         | false    | Customized validation function.                              |
| value        | string |         | true     | The value of the `Input` element.                            |



<h3>Sidebar</h3>

Sidebars for navigation.

<h5>Import</h5>

```typescript
import { Sidebar } from '@symply.io/basic-components/';
// or 
import Sidebar from '@symply.io/basic-components/Sidebar'; 
```

<h5>Sidebar Item Props</h5>

| Name         | Type                      | Default                               | Required | Description                                                  |
| ------------ | ------------------------- | ------------------------------------- | -------- | ------------------------------------------------------------ |
| badge        | number                    |                                       | false    | The badge will be rendered for notifications.                |
| beta         | boolean                   |                                       | false    | If `true` the beta tag will be rendered.                     |
| betaTagColor | CSSProperties["color"]    | \#00A2A9                              | false    | The value of the `Input` element.                            |
| children     | Array\<SidebarItemProps\> |                                       | false    | If not undefined the sub sidebar items would be rendered.    |
| icon         | Element                   |                                       | true     | The icon adornment.                                          |
| lock         | boolean                   |                                       | false    | If `true` the lock icon will be rendered, and the sidebar item would be disabled. |
| name         | string                    |                                       | true     | The sidebar item label.                                      |
| path         | string                    |                                       | true     | The link path of the sidebar item.                           |
| titleForLock | string                    | "Feature is unavailable on Free plan" | false    | The tip when the lock is `true`                              |

<h5>Props</h5>

| Name         | Type                      | Default | Required | Description                                |
| ------------ | ------------------------- | ------- | -------- | ------------------------------------------ |
| items        | Array\<SidebarItemProps\> |         | true     | Sidebar items.                             |
| showIconOnly | boolean                   | false   | false    | If `true` it will show the main icon only. |



<h3>SocialInput</h3>

Input component for Social Security Number (SSN). 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { SocialInput } from '@symply.io/basic-components/';
// or 
import SocialInput from '@symply.io/basic-components/SocialInput'; 
```

<h5>Props</h5>

| Name       | Type   | Default | Required | Description                                                  |
| ---------- | ------ | ------- | -------- | ------------------------------------------------------------ |
| onChange   | func   |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| onValidate | func   |         | false    | Customized validation function.                              |
| value      | string |         | true     | The value of the `Input` element.                            |



<h3>TabGroup</h3>

Tabs group. 

It is extended from `@mui/material/Tabs`, so it includes all properties of `@mui/material/Tabs`.

<h5>Import</h5>

```typescript
import { TabGroup } from '@symply.io/basic-components/';
// or 
import TabGroup from '@symply.io/basic-components/TabGroup'; 
```

<h5>Props</h5>

| Name            | Type                                                         | Default                                                      | Required | Description                                                  |
| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ |
| currentTabIndex | number                                                       | 0                                                            | true     | the tab index from the higher component                      |
| onChange        | func                                                         | If `onChange` is undefined and the `url` of tab is defined, we will navigate to that url when the tab changed | false    | Callback fired when the `Tab` is changed.<br />**Signature:**<br/>`function(args: {tabIndex: number; url?: string}) => void`<br/>*tabIndex:* The selected index of the `Tab` element.<br/>*url*: The url for navigating. |
| tabs            | Array\<{ key: string; text: string; url?: string; disabled?: boolean }\> |                                                              | true     | All tab items.                                               |
| variant         | 'standard' \| 'scrollable' \| 'fullWidth'                    | 'scrollable'                                                 | false    | Determines additional display behavior of the tabs           |



<h3>TablePagination</h3>

Reusable pagination component for the material table

<h5>Import</h5>

```typescript
import { TablePagination } from '@symply.io/basic-components/';
// or 
import TablePagination from '@symply.io/basic-components/TablePagination'; 
```

<h5>Props</h5>

| Name                | Type            | Default | Required | Description                                                  |
| ------------------- | --------------- | ------- | -------- | ------------------------------------------------------------ |
| colSpan             | number          |         | false    | The number of columns a cell should span.                    |
| count               | number          |         | true     | The total count of all data.                                 |
| onPageChange        | func            |         | true     | Callback fired when the `page` value is changed.<br />**Signature:**<br/>`function(event: MouseEvent<HTMLButtonElement> ) => void,value: number`<br/>*value:* The value of the `page` . |
| onRowsPerPageChange | func            |         | true     | Callback fired when the `Select` value is changed.<br />**Signature:**<br/>`function(event: ChangeEvent<HTMLInputElement ` |
| page                | number          |         | true     | The current page index.                                      |
| rowsPerPage         | number          |         | true     | How many rows per page.                                      |
| rowsPerPageOptions  | Array\<number\> |         | true     | The options for setting how many rows per page.              |



<h3>TextInput</h3>

Regular Input component. 

It is extended from `@mui/material/TextField`, so it includes all properties of `@mui/material/TextField`.

<h5>Import</h5>

```typescript
import { TextInput } from '@symply.io/basic-components/';
// or 
import TextInput from '@symply.io/basic-components/TextInput'; 
```

<h5>Props</h5>

| Name      | Type      | Default | Required | Description                                                  |
| --------- | --------- | ------- | -------- | ------------------------------------------------------------ |
| maxLength | number    | 999     | false    | The max length of the `Input` element you can type in.       |
| minLength | number    | 0       | false    | The min length of the `Input` element you should type in.    |
| onChange  | func      |         | true     | Callback fired when the `Input` value is changed.<br />**Signature:**<br/>`function(value: string) => void`<br/>*value:* The value of the `Input` element. |
| tooltip   | ReactNode |         | false    | A tooltip for the `Input` element.                           |
| value     | string    |         | true     | The value of the `Input` element.                            |



<h3>ToastPrompt</h3>

Global prompt component. 

<h5>Import</h5>

```typescript
import { usePrompt } from '@symply.io/basic-components';
```

<h5>Usage</h5>
```typescript
const { showPrompt, hidePrompt } = usePrompt();
```

<h5>Props</h5>

| Name    | Type                                        | Default | Required | Description                                                  |
| ------- | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------ |
| message | string \| 400                               |         | true     | The prompt message you want to show.                         |
| timeout | number                                      | 3500    | false    | The number of milliseconds to wait before automatically calling the `onClose` function. |
| type    | 'success' \| 'warning' \| 'info' \| 'error' |         | true     | The type of prompt.                                          |
| action  | ReactNode \| null                           |         | false    | Customized button(s) at the end of the prompt. If this property is set, the default close icon button will be replaced directly. |



<h3>VideoPlayerModal</h3>

A modal for playing videos. 

<h5>Import</h5>

```typescript
import { VideoPlayerModal } from '@symply.io/basic-components/';
// or
import VideoPlayerModal from '@symply.io/basic-components/VideoPlayerModal';
```

<h5>Props</h5>

| Name         | Type                 | Default | Required | Description                                                  |
| ------------ | -------------------- | ------- | -------- | ------------------------------------------------------------ |
| extraButtons | Array\<ButtonProps\> |         | false    | Extra buttons next to the Close button at the bottom.        |
| onClose      | func                 |         | true     | Callback fired when the cancel button requests to be clicked.<br />**Signature:**<br/>`function() => void` |
| open         | bool                 |         | true     | If `true`, the component is shown.                           |
| pip          | bool                 |         | false    | If `true`, the video can be played in picture                |
| title        | string               |         | false    | Modal title, it would be shown at the top left.              |



<h3>VirtualDataTable</h3>

Reusable data table component with virtualizer

<h5>Import</h5>

```tsx
import { VirtualDataTable } from '@symply.io/basic-components';
// or 
import VirtualDataTable from '@symply.io/basic-components/VirtualDataTable'; 
```

<h5>Column Props</h5>

| Name      | Type                          | Default | Required | Description                                                  |
| --------- | ----------------------------- | ------- | -------- | ------------------------------------------------------------ |
| accessor  | string                        |         | true     | The key of the column, it should be unique.                  |
| align     | "left" \|"center" \|"right"   |         | false    | The alignment of the column.                                 |
| Body      | ReactElement                  |         | true     | The component to render the column body cell.                |
| fixable   | "left" \| "right" \|undefined |         | false    | If not undefined, the column can be frozen. <br/>⚠️ It doesn't work with IE11. |
| Footer    | ReactElement                  |         | false    | The component to render the column footer cell.              |
| Header    | ReactElement                  |         | true     | The component to render the column header cell.              |
| headerTip | string                        |         | false    | The tip title text when the mouse is over the header.        |
| sortable  | bool                          |         | false    | If true, the column can be sortable.                         |
| width     | number                        |         | false    | The fixed width of cells.                                    |

<h5>Sorting Props</h5>

| Name     | Type                      | Default | Required | Description            |
| -------- | ------------------------- | ------- | -------- | ---------------------- |
| accessor | string                    |         | true     | The key of the column. |
| order    | "ASC" \| "DESC" \| "NONE" |         | true     | The sorting order.     |


<h5>Component Props</h5>

| Name                  | Type                       | Default        | Required | Description                                                  |
| --------------------- | -------------------------- | -------------- | -------- | ------------------------------------------------------------ |
| aux                   | {[name:string]: any}       |                | false    | Extra properties                                             |
| columns               | Array                      | []             | true     | Table columns                                                |
| dense                 | bool                       |                | false    | If `true` the table size/density would be tight.             |
| footerBgColor         | CSSProperties["color"]     |                | false    | Customized footer background color.                          |
| footerTextColor       | CSSProperties["color"]     |                | false    | Customized footer text color.                                |
|                       |                            |                |          |                                                              |
| headerBgColor         | CSSProperties["color"]     |                | false    | Customized header background color.                          |
| headerTextColor       | CSSProperties["color"]     |                | false    | Customized header text color.                                |
| initialState          | { sortBy?: SortingProps}   |                | false    | Set the initial states                                       |
| maxHeight             | number                     |                | false    | The max height (px) of the table container.                  |
| noDataText            | string                     | 'No Data!'     | false    | The text when no data rendered.                              |
| onContextMenu         | func                       |                | false    | The function for row right-clicking.<br />**Signature:**<br/>`function(event: MouseEvent, row: RowProps) => unknown` |
| onCustomizeRowBgColor | func                       |                | false    | The function for customizing the row background color.<br />**Signature:**<br/>`function(props: {row: RowProps, columns: Array\<ColumnProps\>}) => {normal?: HexColor;<br/>  hover?: HexColor;<br/>}` |
| onRowClick            | func                       |                | false    | The function for row clicking.<br />**Signature:**<br/>`function(row: RowProps) => unknown` |
| onSort                | func                       |                | false    | The function for sorting rows.<br />**Signature:**<br/>`function(props: SortingProps) => unknown` |
| rows                  | Array<{ [name]: unknown }> |                | true     | Table data/rows.                                             |
| sortingDisabled       | bool                       |                | false    | If true, the whole table can't be sortable.                  |
| visibleRows           | Array<{ [name]: unknown }> | same as `rows` | false    | The table will only display these rows, and it won't affect the table data, especially some totals in the footer (if you defined them). |



<h2>Changelog</h2>

If you have recently updated, please read the [changelog](https://github.com/baseline-software/symply-basic-components/releases) for details of what has changed.