Skip to content
Textkernel OneUI library of reusable UI components
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.storybook feat(ListItem): Allow context highlighting in ListItem (#132) Jul 11, 2019
example build: enhanced dev and prod build modes Jun 28, 2019
scripts build: enhanced dev and prod build modes Jun 28, 2019
src feat(List): added keyboard navigation (#140) Jul 18, 2019
stories Revert "feat(component): new Modal component" Jul 17, 2019
.babelrc Add @babel/polyfill to support IE Sep 27, 2018
.browserslistrc Declate supported browsers in .browserslistrc Sep 25, 2018
.editorconfig Add .editorconfig rules for conde consistency Sep 25, 2018
.eslintignore Set up Coveralls reporting Feb 4, 2019
.eslintrc.json style: require EOF newline and component displayName (#126) Jun 19, 2019
.gitignore Fix: move general dependencies to peer-dependencies (#99) May 13, 2019
.npmrc Add .npmrc to strict out npm --save settings Sep 25, 2018
.prettierrc style: require EOF newline and component displayName (#126) Jun 19, 2019
.stylelintrc Add stylelint-order css linter Nov 20, 2018
.travis.yml Storybook CD (#81) Mar 27, 2019
CHANGELOG.md chore(release): 4.0.1 Jul 12, 2019
CONTRIBUTING.md docs: extend documentation about releasing and commit message format (#… Jun 27, 2019
LICENSE Add MIT license Sep 25, 2018
README.md docs(readme): add bundle size badge Jun 14, 2019
RELEASING.md docs: extend documentation about releasing and commit message format (#… Jun 27, 2019
package-lock.json Revert "feat(component): new Modal component" Jul 17, 2019
package.json Revert "feat(component): new Modal component" Jul 17, 2019

README.md

Textkernel OneUI

npm version Build Status Coverage Status Language grade: JavaScript npm bundle size

Library of reusable React components with theming support

Getting started

For live examples of all OneUI components, click here.

Install with npm

Within your project’s frontend root, install the package from NPM. Make sure it’s marked as production dependency.

$ npm i '@textkernel/oneui'

Set up boilerplate

Import OneUI base stylesheet

In your application main Javascript, make sure to import the OneUI base stylesheet. The base stylesheet includes the default OneUI theme.

import '@textkernel/oneui/dist/oneui.min.css';

Custom themes and browser support

To enable support for older browsers that don’t support CSS variables natively and to apply custom a theme, OneUI comes with a utility that takes on all of these responsibilities. See Theming for more on custom themes.

To apply a specific theme on top of the library components, the OneUI utility can be used to parse the provided theme file:

import OneUI from '@textkernel/oneui';

OneUI.init({
    themeURL: 'http://theme-cdn.com/my-theme.css'
}).then(() => ReactDOM.render(
    <MyApp />,
    document.getElementById('root')
));

The utility can take three optional arguments:

  • themeURL: URL that provides the file containing the CSS variables that will be used instead of the default ones.
  • maxTime: The maximum amount of time in milliseconds that the loader will wait to parse the external theme, otherwise it will fallback to the default library theme. By default, the timeout is set to 2000 milliseconds.
  • ponyfillOptions: Allow the developer to override the default css-vars-ponyfill configuration.

IE11 support

OneUI relies on browser support for CSS variables. Support for older browsers such as IE11 can be enabled by using a polyfill. Using the previously mentioned utility will take care of it automatically.

Using components

  1. Import the desired UI component(s) from the library, e.g.:
import { Alert } from '@textkernel/oneui';
  1. Include the component on your page:
<Alert context="info" title="Hey there!">
    This is some information for you
</Alert>

Undocumented props

Please note that any properties that are not documented in the component prop types definition are applied to the top level HTML element unless mentioned otherwise. These undocumented props are also not described in Storybook.

Examples & Testing

Storybook

OneUI comes with a Storybook of examples for all components. Click here to check it out.

In order to run it yourself locally...

  1. Make sure you have Storybook installed (globally):
$ npm i -g @storybook/cli
  1. Within the OneUI root, run npm run storybook
  2. Go to http://localhost:9001 to check out examples of all OneUI components

Example of implementation

An implementation example can be found in the example directory, along with instructions on how to run it.

Testing

  • Run tests: npm test
  • Coverage report: npm run test:coverage

Theming

All CSS variables (‘custom properties’) exposed by OneUI can be customized, except for color shades (e.g. --color-primary-25) which are computed when generating new themes. A theme file is an additional stylesheet that consists of a reassignment of all variables with values that are different from their defaults. Theme files should not contain any CSS selectors or properties - only CSS variables and values, e.g.:

--color-primary: red;
--color-brand: blue;
--font-size-base: 12px;

Contributing

  • Did you find a bug or do you have a feature proposal? Please open a new issue.
  • If your IDE does not support EditorConfig, please install a plugin (e.g. for VS Code).
  • Please make sure to read the developer guidelines before contributing.

Copyright

Code and documentation © 2019 Textkernel B.V.

You can’t perform that action at this time.