0.0.4 • Published 4 years ago

rc-adminlte v0.0.4

Weekly downloads
1
License
MIT
Repository
github
Last release
4 years ago

rc-adminlte

Yet another project based on the great AdminLTE Control Panel Template. This is not because of a not invented here syndrom but because the other projects seem not very active or did not meet the expectations I had in using such a react component. The philosophy for this project was to make it as easy as possible to use from a developer standpoint and rework it where I've seen the use to. Currently it does still depend on jQuery here and there (especially the DataTables Component).

Samples can be found under react.sper.at and sourcecode on github

Installation

npm i rc-adminlte

Hello-World

Easiest to achieve with create-react-app. Create a new project using cra and install rc-adminlte. Copy this to App.js created by create-react-app

import React, { Component } from 'react';
import AdminLTE, { Sidebar, Content, Row, Col, Box, Button } from 'rc-adminlte';

const { Item } = Sidebar;

class HelloWorld extends Component {
  state = {}

  render() {
    return (<Content title="Hello World" subTitle="Getting started with rc-adminlte" browserTitle="Hello World">
      <Row>
        <Col xs={6}>
          <Box title="My first box" type="primary" closable collapsable footer={<Button type="danger" text="Danger Button" />}>
            Hello World
          </Box>
        </Col>
        <Col xs={6}>
          <Box title="Another box">
            Content goes here
          </Box>
        </Col>
      </Row>
    </Content>);
  }
}

class App extends Component {

  sidebar = [
    <Item key="hello" text="Hello" to="/hello-world" />
  ]

  render() {
    return (
      <AdminLTE title={["Hello", "World"]} titleShort={["He", "we"]} theme="blue" sidebar={this.sidebar}>
        <HelloWorld path="/hello-world" />
      </AdminLTE>
    );
  }
}

export default App;

Components

General UI Type/Coloring options

Several components have a property type or color that allows the usage of the following values to give different accents to the component

Types and Colors

TypeColorColorCode
defaultgray#d2d6de
primarylight-blue#3c8dbc
infoaqua#00c0ef
successgreen#00a65a
warningyellow#f39c12
dangerred#f56954

Additional Colors

In addition there are several colors available without a corresponding type | Color | | ----- | | navy | | teal | | purple | | orange | | maroon | | black |

Icons

AdminLTE makes use of font-awesome icons and ionicons. Since we wanted to stay up to date, we migrated font awesome to version 5.x. Therefore the syntax for icons is no longer fa-icon but instead far/fas/fab-icon. All available icons can be found on the respective websites (font-awesome, ionicons)

AdminLTE

Props
NameTypeDefaultDescription
childrennodeNavbarMenu, Sidebar and Content Components belong here
titleoneOf: string, [string]['Admin', 'LTE']Title in header bar, if an array is supplied the first element will be rendered bold and the second normal
titleShortoneOf: string, [string]['Admin', 'LTE']Title in header bar when the sidebar is collapsed, if an array is supplied the first element will be rendered bold and the second normal
themeoneOf: 'black-light', 'black', 'blue', 'blue-light', 'green', 'green-light', 'purple', 'purple-light', 'red', 'red-light', 'yellow', 'yellow-light''blue'Colortheme for AdminLTE
browserTitlestringUntitledBrowsertitle, can be set here globally or for each site indvidually
sidebararrayOf: <Item />, <Header />, <li />Sidebar items

Sidebar

Item

This component is used to render the sidebar entries. Multilevel entries can be achieved by simply passing furhter items as children.

Props
NameTypeDefaultDescription
idstring
textstringDisplay text of the item
children<Item />A nested Item will be displayed as a sublevel item and allows for multilevel menus
iconicon'far-circle'Icon on the left side
tostring'#'Relative links should refere to anonther page components path property and absolute links are simple anchors
labelsarrayOf: {small: boolean, color: string, text: string, type:string}Description for one or more labels
colorstringIconcolor
isSubItembooleanTrue if its a nested sidebar item, will be set automatically

Header

Header is used to seperate side bar items into multiple groups

Props
NameTypeDefaultDescription
textstringDisplay text of the item

UserPanel

Include a user information in the sidebar

Props
NameTypeDefaultDescription
usernamestringDisplay the username
imageUrlstringShow a image besides the name
linkstringInclude a link to a detail page
statusstringShow the user status
statusTypetypeColor the user status

Searchbar

Provide a sitewide search bar inside the sidebar

Props
NameTypeDefaultDescription
includeButtonboolShow search icon/button
onButtonClickfuncOn click action
onChangefuncOn search change
placeholderstringSearchfield placeholder
valuestring
defaultValuestring

Navbar

It is possible to enhance the top navigation bar with clickable icons and dropdown menus to show additional interactions (e.g. notification bars)

Core

To use the navbar menu you have to wrap Entries with the Core component

<Navbar.Core>
  <Entry
    icon="fas-envelope"
  >
    <MessageItem>
    ...
  </Entry>
</Navbar.Core>

Entry

An entry is the component rendered inside the navbar it can be either used as an additional button (e.g. for logout actions) or as an menu opener rendering components of type MessageItem, NotificationItem, TaskItem. Additionally an colored label can be attached indicating that several actions are behind the menu. If it should act as an button provide the onClick prop otherwise provide some children to use it as an menu.

NameTypeDefaultDescription
iconiconEntry icon
labelTypetypeLabel accent
labelValuenumberLabel value displayed on top right of entry. If you provide no value, the value is calculated as the number of nested children, to disable the label in this case provide a value of 0
headerTextstringText above menu items in opened state
footerTextstringText bellow menu items in opened state
onFooterClickfunctionAction triggered on footer click
classNamestringAdditional classes
childrenoneOf: NotificationItem, TaskItem, MessageItemAdditional classes
onClickfunctionOn click action

NotificationItem

A simple notification style navbar list item with icon

NameTypeDefaultDescription
iconiconIcon left of text
iconColorcolorIcon color
textstringItem text
tostringReact dom route
onClickfunctionOn click action

TaskItem

Navbar item with progressbar

NameTypeDefaultDescription
valuenumberProgress value
barColorcolorProgressbar color
textstringItem text
tostringReact dom route
onClickfunctionOn click action
minnumber0Progress minimum value
maxnumber100Progress maximum value

MessageItem

Instant message style notification

NameTypeDefaultDescription
textstringItem text
subTextstringAdditional text
imageUrlstringUser image link
imageAltstringUser image link
onClickfunctionOn click action
whenmomentObjectProgress minimum value
whenFormatsobject{ minutes: 'mins', hours: 'hours', today: 'today', yesterday: 'yesterday', days: 'DD.MM.YYYY', }Alternative namings for when annotation in item

Content

Main content container for normal and modal content

Props
NameTypeDefaultDescription

Box

Props
NameTypeDefaultDescription
idstring
titlestringBoxtitle
collapsablebooleanfalseToggles the possibility to minimize
closablebooleanfalseToggles the possibility to close a box
headernodeContent to be rendered in the header position of the box
footernodeContent to be rendered in the footer position of the box
typetypeBox accent
optionsnodeIcon with options placed next to the close, collapse icons
iconiconBoxicon
titleRightbooleanfalseRight align box title
loadedbooleantrueLoading spinner for ajax content
noPaddingbooleanfalseRemoves box padding for tighter fitting
badgeBadge, arrayOf: BadgeBadge(s) placed in header
toolIconiconwrenchCustom icon for tools menu
customOptionsnodeOptions for tool menu in header
classNamestring
footerClassstringcustom className for the footer region
collapsedbooleanfalseInitial collapsed state
solidbooleanfalseSolid box styling option
textCenterbooleanfalseCentered text styling in body
paddingbooleanfalseAdditional body padding
bodyClassNamestringcustom className for the body region
borderbooleanfalseVisible border around box
stylestylenullInline style info for the box
childrennodeBox content rendered in body

Col

react-bootstrap Col component

Row

react-bootstrap Row component

Alert

Props
NameTypeDefaultDescription
idstring
closablebooleanfalseMake alert closable
typetypeAlert acent
iconiconIcon display left to text
titlestringAlert title
childrennodeAlert content

Badge

Props
NameTypeDefaultDescription
idstring
colorcolorBadge color
textstringBadge text

Button

As mentioned in react-bootstrap, React does not render new elements on new lines thus buttons side by side will be rendered without margin, to counteract that you can wrap your <Button/>'s with <ButtonGroup />

Props
NameTypeDefaultDescription
idstringButton id
sizeoneOf: 'xs', 'sm', 'md', 'lg'Button size
typetypedefaultButton accent
blockbooleanDisplay as block
iconiconButton icon
colorcolorButton color can be used instead of type
classesstringButton additional button classes
flatbooleanfalseFlat button styling
textstringButton text
pullRightbooleanfalsePull button right
pullLeftbooleanfalsePull button left
disabledbooleanfalseDisable button
marginbooleanfalseAdditional margin around button
tostringfalseButton link, relative uri's should be valid router routes
appbooleanfalseApp button styling
outlinebooleanfalseButton outline styling
badgeBadge, arrayOf: BadgeBadge placed in button
onClickfunctionOn click action
splitbooleanfalseSplit button and submenu
childrennodeButton submenu entries

ButtonGroup

Props
NameTypeDefaultDescription
pullRightbooleanfalsePull button group right
marginbooleanfalseAdditional margin around button group
verticalbooleanfalseVertical align button group
children<Button />Button rendered in group

Calendar

Work in progress

jQuery full calendar component

Props
NameTypeDefaultDescription

Callout

Props
NameTypeDefaultDescription
idstring
typetypeCallout accent
titlestringCallout title
childrennodeCallout content

Chatbox - Work in progress

Undocumented use at your own risk

Checkbox

SimpleTable

Props
NameTypeDefaultDescription
dataarrayArray of objects matching the column description
columnsarrayColumn descriptions, see next table for reference
condensedboolfalseCompact data layout
stripedboolfalseAlternate row coloring
noMarginboolfalseRemoves table margin
borderboolfalseShow borders around cells
responsiveboolfalseResize table of window resize
hoverboolfalseHighlight hovered rows
Column Options
NameTypeDefaultDescription
titlestringColumn title
datastringData property containing the data to be rendered in the column
widthstringUse this prop to give the column a fixed width
renderfunctionCustom render function for the column with arguments (data, rowData, rowIndex)

DataTable

Props
NameTypeDefaultDescription
optionsobjectArray of objects matching the column description
ajaxMapfunctionAllows custom argument mapping for ajax based data source, equivalent to on('preXhr.dt')
ajaxResponseMapfunctionMapping function for data retrieved on ajax based data source, equivalent to on('preXhr.dt')
dataarrayArray of objects matching the column description
columnsarrayColumn descriptions, see next table for reference
setDataTableReffunctionCallback that gets passed the datatable api() ref
onSelectfunctionCallback after row gets selected - arguments (rowdata)
onDeselectfunctionCallback after row deselect - arguments (rowdata)
footerboolfalseRenders column headers on bottom of table
hoverboolfalseHighlight hovered rows
borderboolfalseShow borders around cells
condensedboolfalseCompact data layout
stripedboolfalseAlternate row coloring
noMarginboolfalseRemoves table margin
responsiveboolfalseResize table of window resize
selectedRows[object]Allows passing in the currently selected rows
onClickEventsobjectRow level bound click events based on class on cell dom element. Example render: (data) => ``<div class="on-click-event">${data}</div>``' will bind to an object {onClickEvent: (data, rowIndex, rowData) => {console.log("do stuff with row data")}}
pagenumberActive page, can be left empty if uncontrolled
totalElementsfuncPassing this property or hasMore makes this component controlled, therefore pageSize, pageChange and orderChange props should be provided too
pageSizenumberAllows passing in the currently selected rows
onPageChangefuncPage change event handler
onOrderChangefuncOrder change event handler
hasMoreboolIf you control data externally and are not exactly aware if additional pages exist you can provide hasMore instead to indicate if more data exists
order[object]Allows passing in the currently selected rows
searchValuestringSearch value for datatable search field
onSearchChangefuncSearch value change event
Order props
NameTypeDefaultDescription
titlestringColumn title
datastringData property containing the data to be rendered in the column
widthstringUse this prop to give the column a fixed width
renderfunctionCustom render function for the column with arguments (data, rowData, rowIndex)

Description

Simple wrapper over <dl>

Props
NameTypeDefaultDescription
idstring
horizontalboolfalseWill render the list horizontal

DescriptionItem

Props
NameTypeDefaultDescription
textstring
labelstring
noTextboolfalseUse this if you only want to render a label

DescriptionBlock

A block content element containing several text elements (text and header) a percentage description and indicator.

Props
NameTypeDefaultDescription
idstring
percentagenumber
percentageColorcolor
headerstring
textstring
indicationoneOf: left, right, up, down

Divider

Include a divider to give a better distinction between sidebar entries

Infobox

Infobox with icon, text and optional progress information

Props
NameTypeDefaultDescription
idstring
iconicon
textstring
numberstringBold text displayed in center, usually a number
colorcolor
progressnumber
progressTextstring
iconColorOnlystringAlternate styling that colors only the icon instead of the entire box

Infobox2

An alternative info box with similar props but other styling

Props
NameTypeDefaultDescription
idstring
iconicon
colorcolor
titlestring
subTitlestring
textstring
footerTextstring
footerIconiconfas-arrow-alt-circle-right
onFooterClickfunctionCallback on footer click
torouteCan be used instead of onFooterClick to route instead to another page directly

Label

LoadingSpinner

LoginCore

Margin

Memberbox

NavList

NavListItem

Pagination

ProductList

ProductListItem

ProgressBar

ProgressGroup

Sparkbar

SparklineBox

Tabs

Wrapper around react-bootstrap tabs, this can be either used as uncontrolled tabs by providing a defaultActiveKey property or a controlled tabs using activeKey and onSelect props

Props
NameTypeDefaultDescription
idstring
activeKeystringCurrently active tab, if you provide an activeKey you should also provide an onSelect event handler prop
defaultActiveKeystringInitially active tab, similar to react behaviour of defaultValue on <input> components this prop provides an inital state for uncontrolled tabs
onChangefunctionEvent handler fired when a tab is changed
childrenTabContentProvide multiple TabContent as child to render anything in tabs
pullRightboolfalsePulls the tab header to the right side
contentHeightstringIf the content height varies you can provide a fixed height to prevent moving elements when changing between tabs
mountOnEnterfalseAdds the tab content to react's virtual dom at the first them it is selected
unmountOnExitfalseRemoves inactive tabs from react virtual dom
iconiconHeader icon besides the title
titlestring
titleLeftboolfalsePulls the title to the left side when using the pullRight property

TabContent

Use TabContent in conjuction with Tabs to actually provide the tabular content

Props
NameTypeDefaultDescription
eventKeystringUnique key used by Tabs to identify the currently active tab
childrennodeTabular content

Forms

A various of different form elements, ranging from simple default html forms (Text, Radio, Select, Checkbox) to advanced components based on jQuery Widgets like Select2, ICheck used by the original adminlte template and pure react based inputs like Date, DateRange (based on react-dates), Slider (based on rc-slider) and other components. All form components should behave like original react inputs with defaultValue's and onChange passing more or less pure Javascript event objects to make it possible to work with libraries like Formik. Note that all form elements are not directly exported by AdminLTE instead you should import Inputs and destructure the required elements.

import AdminLTE, { Inputs } from 'rc-adminlte';

const { Select2, Date, DateTime, Text } = Inputs;
...

All form elements are wrap in the Component InputWrapper with various styling options such as icons, radio buttons, therefore all following props are shared between all form elements. If you want to add an additional element you can also wrap it with InputWrapper to fit it smooth into the styling of all other elements. Additional all inputs share the same labeling props to keep a similar styling.

The following InputWrapper and Label props are shared within all of rc-adminlte input components

InputWrapper Props
NameTypeDefaultDescription
iconLefticonIcon left of element
iconRighticonIcon right of element
addonLeftstring, nodeAny content left of element
addonRightstring, nodeAny content right of element
sizeoneOf: 'xs', 'sm', 'md', 'lg'Inputform size
checkboxLeftboolCheckbox left of element
checkboxLeftPropsobjectProps for checkbox left of element
checkboxRightboolCheckbox right of element
checkboxRightPropsobjectProps for checkbox right of element
radioLeftboolRadio left of element
radioLeftPropsobjectProps for radio left of element
radioRightboolRadio right of element
radioRightPropsobjectProps for radio right of element
buttonLeftnodeButton rendered left of element
buttonRightnodeButton rendered right of elemet
childrennode
widthstringFixed inputfield width
helpstringHelp text bellow input element
Label Props
NameTypeDefaultDescription
labelnodeLabel for form element, can be a simple string or a more complex JSX component
labelIconiconIcon next to label
labelPositiononeOf: above, left, noneleft
labelClassstringAdditional label classes
typetypeInput element accent
namestringName property for screenreaders
labelXsnumber (0-12)Bootstrap label column width, does only work when labelPosition left is used
labelSmnumber (0-12)Bootstrap label column width, does only work when labelPosition left is used
labelMdnumber (0-12)Bootstrap label column width, does only work when labelPosition left is used
labelLgnumber (0-12)Bootstrap label column width, does only work when labelPosition left is used
xsnumber (0-12)Bootstrap input element column width, does only work when labelPosition left is used
smnumber (0-12)Bootstrap input element column width, does only work when labelPosition left is used
mdnumber (0-12)Bootstrap input element column width, does only work when labelPosition left is used
lgnumber (0-12)Bootstrap input element column width, does only work when labelPosition left is used

Text

Slider

A slider component that can be used either as a single slider or a (multi) range slider, it is based on rc-slider. As with most other components, the most import props/usedful props are directly exposed. All other props can be passed to the wrapped component using the rcSliderProps property.

Props
NameTypeDefaultDescription
colorcolor'light-blue'
defaultValuenumber
valuenumber
onChangefunc
tooltipRenderfunc(value)Custom tooltip render function
tooltipVisibleoneOf: 'always', 'dragging', 'never'Custom tooltip render function
handleelementPass a custom handle directly to rc-slider
rcSliderPropsobjectPass any other rc-slider prop directly to rc-slider, see documentation

Checkbox

Simple unstyled checkbox

Props
NameTypeDefaultDescription
textstringtext next to checkbox
onChangefunc
disabledboolfalse
namestring
valueoneOf: string, numberValue returned when box is checked

Radio

Select

Select2

This component is based on the popular jQuery select2 plugin. It has some improvements and events and select options are adjusted to provide a uniformal coding experience instead of dealing with ever changing api's. Additionally it is possible to provide an externally controlled datasource using onDataFetch callback.

Props
NameTypeDefaultDescription
idstringComponent id
select2OptionsobjectProvide additional select2 options for the jQuery widget, see the select2 homepage for the entire documention of those features
multipleboolAllow multiple value selection
options[object]All available options
valuenumber, string, [number], [string]Selected values
defaultValuenumber, string, [number], [string]defaultValue selected values
disabledboolfalse
namestringName of <input> html field
allowClearboolfalseAllow empty field value
onChangefunctionOn change event handler
onBeforeClosefunctionOn before option select handler
onClosefunctionOn after option select handler
onBeforeOpeningfunctionOn before option select open handler
onOpenfunctionOn after option select open handler
onBeforeSelectfunctionOn before option selection handler
onSelectfunctionOn option selection handler
onBeforeUnselectfunctionOn before option deselect handler
onUnselectfunctionOn option deselect handler
onFetchDatafunction({page, searchValue}, success(data), failure())On data fetch handler, arguments are an object with page no and searchValue current search term, a success callback that should be called with new data and a failure handler on fail
fetchDataDelaynumber100Delay before onFetchData is being call when entering a search value, to prevent overfetching of data

Date

This component in combination with DateRange is heavily based on react-dates with additional simplification and styling based on admin-lte. It should replace bootstrap-datepicker component in the original theme with a pure react alternative. The most common props are directly exposed on the Date component, additional props can be passed by using the dateProps property. The full documentation of available props can be found in react-dates SingleDatePicker documentation

Props
NameTypeDefaultDescription
typetypeCalendar accent
valuestring, moment objectYou can either pass in a string in combination with the format property or an already converted moment.js object, as the original this component used moment as its internal representation. Note that the onChange event will always return a string
formatstringFormat string based on moment.js formatting rules
onChangefunctionOn change event handler
onFocusChangefunctionOn focus change event handler
namestringName that behaves like <input> name prop
placeholderstring
disabledboolfalse
requiredboolfalse
readOnlyboolfalse
screenReaderInputMessageboolfalse
showClearDateboolfalse
customCloseIconnode
showDefaultInputIconboolfalse
customInputIconboolfalse
noBorderboolfalse
blockboolfalse
smallboolfalse
regularboolfalse
inputIconPositionstring
datePropsobjectAdditional SingleDateProps that are not directly exposed, see react-dates SingleDatePicker documentation

DateRange

DateTime

ICheck