bkn-ui
It's a set of React components based on Bootstrap 4 and Google's Material Design, using Reactstrap and react-mdc-web libraries respectively.
It also includes custom styles using SASS.
Table of Contents
Installation
npm install -S -E bkn-uiOr using yarn.
yarn add -E bkn-uiIt has some peer dependencies, so if you not installed them, you have to.
yarn add -E bootstrap@4.0.0-alpha.6 react react-mdc-web reactstrapNote: reactstrap has some peer dependencies as well. See more details in Dependencies section in their website for more details.
Styles
Material Design
bkn-ui was designed with the
Roboto font and
Material Design Icons in mind.
So be sure to include them in your HTML file, in <head> tag:
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" />
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />Bootstrap
All Bootstrap styles are located in SASS files. For example, if you want to import styles for <Layout> component:
@import "node_modules/bkn-ui/scss/theme/base";
@import "node_modules/bkn-ui/scss/components/layout";For more details on how to import the correct styles for any components, see Theming and Components wiki pages.
Getting Started
We are about to see how to implement an application layout that will be composed by a Drawer, a Main Nav, a User dropdown menu and an Welcome message.
This is the end result:
Basic elements
Let's start by <Layout> component.
// LayoutExample.tsx
import * as React from 'react';
import {SFC} from 'react';
import {Layout} from 'bkn-ui';
const LayoutExample: SFC<{}> = () => (
<Layout
drawerHeaderTitle="App Name"
mainNavTitle="App Name"
/>
);
LayoutExample.displayName = 'LayoutExample';This will render a <MainNav> component on top (like an application bar) and a <Drawer> on the left. A button that toggles the <Drawer> will be rendered by default on <MainNav> in left side and on top of <Drawer> as well.
On <Layout> we added two props. drawerHeaderTitle prop will render App Name text on top of <Drawer>. mainNavTitle prop will render same text in left side of <MainNav>.
Drawer content
Our <Drawer> doesn't have any content besides a title. Let's add some content.
import {Nav, NavItem, NavLink} from 'reactstrap';
const drawerContent = (
<Nav vertical>
<NavItem>
<NavLink
className="toggle-drawer active"
href="#"
>
Link 1
</NavLink>
</NavItem>
<NavItem>
<NavLink
className="toggle-drawer"
href="#"
>
Link 2
</NavLink>
</NavItem>
</Nav>
);
// code omitted for brevity
const LayoutExample: SFC<{}> = () => (
<Layout
drawerContent={drawerContent}
drawerHeaderTitle="App Name"
mainNavTitle="App Name"
/>
);As you can see, there's an import statement from reactstrap, instead of bkn-ui. This is because reactstrap is a peer dependency in bkn-ui and a lot of reactstrap components wasn't cutomized by bkn-ui. See reactstrap components for more details.
Also a drawerContent prop was added to <Layout>, holding the drawer content.
User menu
Now, let's add a user menu in the right side of <MainNav>.
import {UserMenu, UserMenuImage} from 'bkn-ui';
const userMenuImage = (
<UserMenuImage
imageUrl="https://s.gravatar.com/avatar/00000000000000000000000000000000?s=480&r=pg"
userName="John Doe"
/>
);
const userMenu = (
<UserMenu userImage={userMenuImage}>
<div>
<div className="d-block">
<strong>John Doe</strong>
</div>
<div className="d-block">johndoe@beakyn.com</div>
<div className="d-block">
<a className="dropdown-menu-link" href="#">Logout</a>
</div>
<div className="dropdown-divider" />
<div className="d-block">
<small>v1.0.0</small>
</div>
</div>
</UserMenu>
);
// code omitted for brevity
const LayoutExample: SFC<{}> = () => (
<Layout
drawerContent={drawerContent}
drawerHeaderTitle="App Name"
mainNavElementRight={userMenu}
mainNavTitle="App Name"
/>
);<UserMenu> renders a dropdown menu. We just add some content to it, as well as an image using <UserMenuImage> component.
Then we passed this to <Layout> via mainNavElementRight prop.
Welcome message
We don't have anything in our layout body. Let's add an welcome message using <Welcome> component.
import {Welcome} from 'bkn-ui';
// code omitted for brevity
const LayoutExample: SFC<{}> = () => (
<Layout
drawerContent={drawerContent}
drawerHeaderTitle="App Name"
mainNavElementRight={userMenu}
mainNavTitle="App Name"
>
<Welcome userName="John Doe">
This is the Welcome component.
</Welcome>
</Layout>
);So, we just include <Welcome> component as a child of <Layout>. Then we passed some content to it.
Beautifying
Okay, let's beautify our UI.
First, we create a LayoutExample.scss file and import the base theme and styles for the components we are using (layout and welcome).
// LayoutExample.scss
@import "node_modules/bkn-ui/scss/theme/base";
@import "node_modules/bkn-ui/scss/components/layout";
@import "node_modules/bkn-ui/scss/components/welcome";Then we simply import that style file in our typescript file.
// LayoutExample.tsx
import './LayoutExample.scss';Note: see Theming section for more details.
Ok, but if you see the result, you'll see that welcome message has not a good spacing with main nav. Let's fix that in next section.
Layout body
To fix spacing between <MainNav> and <Welcome> we going to use the <Page> and <PageBody> components. They work as a <Layout> body adding spacing and a custom scrollbar to the content.
import {Page, PageBody} from 'bkn-ui';
// code omitted for brevity
const LayoutExample: SFC<Props> = ({appName}) => (
<Layout
drawerContent={drawerContent}
drawerHeaderTitle={appName}
mainNavElementRight={userMenu}
mainNavTitle={appName}
>
<Page>
<PageBody>
<Welcome userName="John Doe">
This is the Welcome component.
</Welcome>
</PageBody>
</Page>
</Layout>
);Also we need to add styles for <Welcome> in our SASS file.
// LayoutExample.scss
// code omitted for brevity
@import "node_modules/bkn-ui/scss/components/welcome";That's it! Now go see Components section.
API Reference
Contributing
-
Create an issue describing clearly the new feature or problem.
-
Create a branch with issue name.
-
Improve/Fix it.
-
Generate bundle and types by running:
npm run build -
Bump version in package.json based on SemVer.
-
Create a PR and inform what issue is closed. For example:
Closes #1 -
Approve and merge PR.
-
Delete branch.
-
Publish to npm:
npm publish -
Create a tag for current version. For example:
git tag 1.0.0 -
Push tag to Github.
git push --tags -
Write change log in tag body based on merged PRs. Example here.
-
Be happy. =]