If you're not using reapp-kit, you can use reapp-ui by itself with no extra dependencies. It will require a little more work to get running, but we've purposely kept everything modular so you can choose how much you want to use.
reapp-ui is a set of React components for building beautiful user interfaces for all platforms. It has a few goals:
- Powerful interaction and animations
- Easy to use what you want, and leave the rest
- Themeable in every way
- High performance
The simplest way of using reapp-ui is to load one of our themes, and then import the components you want to use. Here's an example of this;
import iOSTheme from 'reapp-ui/themes/ios/theme'
import Theme from 'reapp-ui/helpers/Theme';
import Button from 'reapp-ui/components/Button';
import React from 'react';
export default React.createClass({
render() {
return (
<Theme {...iOSTheme}>
<Button color="red" />
</Theme>
);
}
});
This will bundle every style for every component in the iOS theme. It's simple and easy to get started with. Reapp themes are very powerful, though, and they allow you to customize every aspect of them.
Let's see how they work. If you open the reapp-ui/themes/ios/theme.js
file
you'll see how we load the iOS theme:
import UI from 'reapp-ui';
UI.addConstants(
require('./constants/base'),
require('./constants/components')
);
UI.addAnimations(require('./animations'));
UI.addStyles(require('./styles'));
export default UI.makeTheme();
As you can see, we're basically loading three different pieces: constants, styles, and animations. We're also loading the stylesheets file which includes our base.css styles that are used to normalize everything.
You could easily override each of these steps by adding in new constants, styles, or animations, or overwriting the ones we use!
The rest of the docs here describe the internals of reapp-ui. If you want to learn more on how Reapp works, check out:
- Components & Views: The building blocks of reapp-ui
- Packages: Information on the other packages that come with reapp
- Animations: How to make custom animations
- Themes: Themes in depth
- Building & Cordova: How to build your app for the web, iOS and other platforms
You can add these demos to your home screen or emulate mobile on your browser:
A note on speed: Your apps will run significantly faster when they are built. When running in dev mode they are not only checking PropTypes and for a variety of warnings, but they also aren't running using requestAnimationFrame which means they tax the CPU a lot more (but in exchange are easier to debug).
/assets
Icons, etc
/behaviors
(!) Used within components, can be passed in to override
/components
The UI components
/helpers
Components which don't map directly to user-viewable, helper components
/lib
Internally used functions
/mixins
All mixins (used internally and externally)
/stores
Internal: should be removable once parent-based contexts are in React
/themes
Theme files users can require
index.js
Used to set up reapp-ui.
reapp-ui uses three different things that must be imported at initialization. These things are imported so they can be mixed and matched for use with adapting theme or behavior.
For now it has three relevant methods:
-
addConstants
: constants allow users to customize themes easily. They are used in styles (and in the future could be used with animations and more). See /themes/ios/constants/ for examples.* -
addStyles
: styles objects, keys map to the names of components and values are objects that are CSS styles in JS. Values can optionally be a function, that takes in the constants as the argument. See /themes/ios/styles/ for examples.* -
addAnimations
: animations are objects, keys are names, values are functions that take an object withindex
,step
as keys, an optionally extra keys with more info. See /themes/ios/animations.js for examples.
To see how you'd make a theme, we suggest looking at /themes/ios/theme.js
. You
can require that file to have the entire iOS theme setup for you automatically.
component.js
component is a decorator that is used internally by reapp-ui to make components. It was extracted out and is a nice set of mixins that allow the ui components to avoid repetitious code.
This is an important file to inspect before understanding how this library works, and from there, the Mixins that are used here make the foundation of the UI kit.
Because Reapp is split into a number of modules, you'll probably need to do a little more work than usual to contribute. For the UI, the best setup is to do the following:
- Create a
reapp
folder - Clone the kitchen sink repository
- Clone this repository
- Run
sudo npm link
inside this repository - Important: Run
rm -r node_modules/react
in reapp-ui and be sure react isn't duplicated in Webpack build - Run
npm run build
in this directory, this will build your reapp-ui for the first time and put it into the ./build folder. - Run
npm run copyAssets
in this directory to copy assets to the babel output directory. - Run
npm run watch
in this directory to start babel compiler. Note: Be sure to edit in./src
directory only. - Run
ln -s $PREFIX/lib/node_modules/reapp-ui/build node_modules/reapp-ui
inside the kitchen sink repository. The placeholder$PREFIX
is the prefix used for the installation of node. Usually this is/usr/local
. The commandnpm config get prefix
can also be used to find the prefix. (Thenpm link
command will not work here because it will reference the project root instead of build output directory.)
This will link your reapp-ui module into your kitchen sink repo. Now you can:
- Run
reapp run -d
inside kitchen sink - Go to localhost:3010
- Make edits inside reapp-ui and they will automatically compile into the kitchen sink.
Warning: When running locally you may run into some unique bugs. Because npm link
runs an npm install
, it will often install multiple versions of React into your
modules folders, causing Webpack to bundle multiple versions of it into your app. This
can cause a variety of errors. If you see stuff that warns about Mount, Link, Context
,
it is most likely because of this. Delete the react folder inside reapp-ui and any other
sub-modules and re-run Webpack.
Original inspiration was thanks to Pete Hunt's React Mobile Demo. The Framework7 Kitchen Sink was used as reference when building the kitchen sink.
SVG Icons included in this repo are originally from flaticon and are licensed under Creative Commons 3.0. If you use them with your project, you must include attribution "in any reasonable manner, but not in any way that suggests the licensor endorses you or your use".
A big part of react-tappable was imported for use as a mixin, and will be sent back as a pull request soon!
Help throughout was given in the #reactjs freenode channel, and from various great members of the react community including:
and many more.