NexusUI Components

These are custom components specially-developed for NexusUI applications. They will make your life easier by giving you out-of-the-box implementations for various high-level UI elements that you can drop directly into your application.

Installation

Add the component as a dependency to your project:

# With yarn
yarn add @nexusui/components

# With npm
npm install --save @nexusui/components

You will also need to install the necessary peer dependencies:

# With yarn
yarn add @mui/material @emotion/react @emotion/styled @mui/x-data-grid @mui/x-date-pickers @mui/icons-material @nexusui/theme

# With npm
npm install --save @mui/material @emotion/react @emotion/styled @mui/x-data-grid @mui/x-date-pickers @mui/icons-material @nexusui/theme

Usage

In your typescript file, import the component(s) you want to use:

// Replace ComponentName with the specific component you want to use
import { ComponentName } from '@nexusui/components';

Also we support path imports.

// Replace ComponentName with the specific component you want to use
import { ComponentName } from '@nexusui/components/ComponentName';

Migration Guide

2.X.X => 3.0.0

Version 3.0.0 includes several breaking changes. If you plan to upgrade to 3.0.0, please follow the upgrade guide below carefully.

1) PeerDependencies updated

A few peer dependency versions have been updated so we can take advantage of new features in these libraries. You'll need to update your dependencies to the following minimum versions:

• @nexusui/theme version 3.0.0 or higher.
• @mui/x-data-grid version 6.5.0 or higher (this affects projects using UserManagement and OrgManagement components).
  • upgrading from version 5 requires additional code changes in your application. Follow the Data Grid Migration from MUI to update your code if you are using any DataGrid components.

2) Renamed Components / Type Changes

- FormInputText renamed to FormInput

// before
import { FormInputText, FormInputTextProps } from '@nexusui/components';

// after
import { FormInput, FormInputProps } from '@nexusui/components';

Additionally, the FormInputProps now inherit from TextFieldProps, resulting in the following type changes:

• label field was required before and is now optional
• name field was not present before and is now required
• controllerProps field was required before and is now optional

// before
<FormInputText label={'label'} controllerProps={{ name: 'test' }}/>

// after
<FormInput name="test" label={'label'} />

-FormInputRadio renamed to FormRadio

// before
import { FormInputRadio, FormInputRadioProps } from '@nexusui/components';

// after
import { FormRadio, FormRadioProps } from '@nexusui/components';

-FormInputToggle renamed to FormToggle

// before
import { FormInputToggle, FormInputToggleProps } from '@nexusui/components';

// after
import { FormToggle, FormToggleProps } from '@nexusui/components';

Additionally, the following type changes apply to the FormToggleProps prop:

• name field was not present before and is now required
• controllerProps field was required before and is now optional

// before
<FormInputToggle controllerProps={{ name: 'test' }}/>

// after
<FormToggle name="test" />

3) GridCard selected state now user-controlled

This selected state of this component has changed from internally managed to user-controlled. We have added a prop selected to control its selected state.

// before, the selection state is controlled inside this component, users don't and cannot control its selection state.
 <GridCard {...otherProps}>{...children}</GridCard>

// after, users must control its selection state by the new 'selected' prop, and this prop is required.
 <GridCard  selected {...otherProps}>{...children}</GridCard>

4) UnitFormatter is now controlled

This component has been updated to be a controlled component to allow for greater control over behavior and integration with 3rd-party form libraries. If you want to continue to have the component manage state internally, we have created a new SimpleUnitFormatter with the legacy behavior.

// before
<UnitFormatter {...props} />

// after
<SimpleUnitFormatter {...props} />

5) CodeSnippet now requires stylesheet inclusion

In order to facilitate using this component in NextJs applications, we removed the automatic import of PrismJS css files. If you are using the CodeSnipper component, you must now manually import these stylesheets in your root TS/JS file.

// before
 <CodeSnippet previewCode={preview} code={code} />

// after
import 'prismjs/themes/prism-okaidia.css';
 <CodeSnippet previewCode={preview} code={code} />

// after with show line numbers
import 'prismjs/themes/prism-okaidia.css';
import 'prismjs/plugins/line-numbers/prism-line-numbers.css';
<CodeSnippet previewCode={preview} code={code} showLineNumbers/>

6) CommentDrawer sorting/filtering and type definitions changed

comments prop type updated to support replies

You can now show replies to comments in the drawer using the replies field in comments prop.

const comments = [{
        {...otherProps}
        replies: [
          {
            id: '3',
            author: { id: '3', firstName: 'Arthur', lastName: 'Lutz', email: '', avatar: '' },
            actions: [{id: 'edit',label: 'Edit',onClick: () => {}},
                      {id: 'delete',label: 'Delete',onClick: () => {}}],
            dateModified: new Date(Date.now() - 3000),
            message: 'Pellentesque ac risus non tortor convallis gravida in eget est. Aenean sed augue ullamcorper, mollis risus eu, venenatis lorem. Fusce pharetra dui ac massa commodo dapibus.',
          },
        ]
      }
    ]

filter and sort responsibility shifted to user

In version 2, this component managed sorting and filtering internally. For greater flexibility in your application, these behaviors must now be controlled by the application code. To support this, we have introduced new props for onFilterChanged and onSortChanged. You can control which comment is active/selected using the new selectedCommentId prop. Refer to the component readme for full API details and usage examples.

7) FileItem status prop replaces loading

The loading prop has been deprecated, and will no longer have any effect. You should instead use the new status prop to control the file status.

// before
 <FileItem loading={false} {..otherProps} />

// after 
// `Uploading` status
import { UploadStatus } from '@nexusui/components';
 <FileItem status={UploadStatus.Uploading} progress={10} {..otherProps} />
// `Succeeded` status
 <FileItem {..otherProps} />
// `Failed` status
 <FileItem status={UploadStatus.Failed} errorMessage={'Upload failed'} onRetry={() => {}} {..otherProps} />

8) ImageCarousel rewritten with react-slick

react-swipeable-views is no longer being actively maintained, so we have rewritten the ImageCarousel component to use react-slick instead.

To update to using the new component, you must make the following changes:

1. Import the react-slick css styles in your root TS/JS file as follows:

import 'slick-carousel/slick/slick.css';
import 'slick-carousel/slick/slick-theme.css';

// ...rest of your code

2. Replace autoplay HOC from react-swipeable-views with new props autoplay and autoplaySpeed

// before
import { ImageCarousel, autoPlay, SwipeableViews } from '@nexusui/components';
export const ImageCarousel = () => {
  return (<ImageCarousel images={[/*images*/]} SwipeableViews={autoPlay(SwipeableViews)} swipeableViewsProps={{ enableMouseEvents: true, interval: 3000 }}/>);
};

// after
import { ImageCarousel } from '@nexusui/components';
export const ImageCarousel = () => {
  return (<ImageCarousel images={[/*images*/]} autoplay={true} autoplaySpeed={3000} />);
};

3. Some higher-order component (HOC) functionality from react-swipeable-views is not supported in the new implementation. If you are using the following HOCs, you will need to remove them:

   • bindKeyboard
   • virtualize

4. Some prop names in swipeableViewsProps have changed:

   • enableMouseEvents => swipe
   • axis => vertical
   • onChangeIndex => afterChange
   • slideRenderer => children

// before
  <ImageCarousel images={[ /*Images*/]}
    swipeableViewsProps={{
      enableMouseEvents: true,
      axis: "x",
      onChangeIndex: (index: number) => {
        console.log("onChangeIndex: ", index);
      },
      slideRenderer: (params: any) => {
        return (<Box><img src={params.src} alt={params.alt} /></Box>);
      },
    }}
  />

// after
  <ImageCarousel
    images={[ /*Images*/ ]}
    swipeableViewsProps={{
      swipe: true,
      vertical: false,
      afterChange: (index: number) => {
        console.log("afterChange: ", index);
      }
      // ...other props
    }}
  >
    {
      [/*Images*/].map((image, index) => {
        return (<img src={image.src} alt={image.alt} key={index} />)
      })
    }
  </ImageCarousel>

For more details, please refer to react-slick;

// before
import { HexSearchComponent } from '@nexusui/components';

// after
import { SearchBar } from '@nexusui/components';

// before
<HexSearchComponent withDebounce={true} {...others}/>
// after
<SearchBar debounce={500} {...others}/> // 500ms is the default

export type IBasicUser = {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  avatar: string;
};

// before
const userInfo: IUserInfo = { name: `Jon Snow`, avatarSrc: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png' };
<AccountDropdown userInfo={userInfo} {...others}/>

// after
const userInfo: IUserInfo = { id: '1', firstName: 'Jon', lastName: 'Snow', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', email: 'jon.snow@hexagon.com' };
<AccountDropdown userInfo={userInfo} {...others}/>

// before
const users: IUserInfo[] = [{userId: '1', firstName: 'Jon', lastName: 'Snow'}];
<AudienceGroup users={users} {...others}/>

// after
const users: IUserInfo[] = [{id: '1', firstName: 'Jon', lastName: 'Snow', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', email: 'jon.snow@hexagon.com'}];
<AudienceGroup users={users} {...others}/>

// before
const author: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow'};
<CommentCard author={author} {...others}/>

// after
const author: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', email: 'jon.snow@hexagon.com'};
<CommentCard author={author} {...others}/>

// before
const author: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow'};
const participants: ICommentAuthor[] = [author];
const comments: IComment[] = [{author, participants, ...{others}}]
<CommentDrawer comments={comments} {...others}/>

// after
const author: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', email: 'jon.snow@hexagon.com'}
const participants: ICommentAuthor[] = [author];
const comments: IComment[] = [{author, participants, ...{others}}]
<CommentDrawer comments={comments} {...others}/>

// before
const user: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow'};
const participants: ICommentAuthor[] = [user];
const comment: IComment = {author: user, participants, ...{others}}
<CommentThread currentUser={currentUser} comment={comment} replies={[{author: user}]} {...others}/>

// after
const user: ICommentAuthor = {id: '1', firstName: 'Jon', lastName: 'Snow', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', email: 'jon.snow@hexagon.com'}
const participants: ICommentAuthor[] = [user];
const comment: IComment = {author: user, participants, ...{others}}
<CommentThread currentUser={currentUser} comment={comment} replies={[{author: user}]} {...others}/>

// before
const users: UserItem[] = [{id: '1', firstName: 'Jon', lastName: 'Snow', email: 'jon.snow@hexagon.com', avatarSrc: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', status: ''}]
<UserManagement users={users} {...others}/>

// after
const users: UserItem[] = [{id: '1', firstName: 'Jon', lastName: 'Snow', email: 'jon.snow@hexagon.com', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', status: ''}]
<UserManagement users={users} {...others}/>

// before
const userInfo: UserItem = {id: '1', firstName: 'Jon', lastName: 'Snow', email: 'jon.snow@hexagon.com', avatarSrc: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', status: ''}
<UserDetail userInfo={userInfo} {...others}/>

// after
const userInfo: UserItem = {id: '1', firstName: 'Jon', lastName: 'Snow', email: 'jon.snow@hexagon.com', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', status: ''}
<UserDetail userInfo={userInfo} {...others}/>

// before
const contact: ContactInfo = {firstName: 'Jon', lastName: 'Snow', name: 'Jon Snow', email: 'jon.snow@hexagon.com', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', mobile: ''}
const userInfo = {contact, ...others}
<UserPreference userInfo={userInfo} {...others}/>

// after
const contact: ContactInfo = {id: '1', firstName: 'Jon', lastName: 'Snow', email: 'jon.snow@hexagon.com', avatar: 'https://i2.wp.com/cdn.auth0.com/avatars/js.png', role: '', mobile: ''}
const userInfo = {contact, ...others}
<UserPreference userInfo={userInfo} {...others}/>