A collection of freely available React.js UI components by Maincode!

Build as a mobile first, batteries included extension for Ionic Framework apps.

> View demo and documentation page

---

Maincode UI strives to deliver quickly integratable components to supplement Ionic or other React.js applications. It is:

• Simplistic but customizable. The components are high level and include several sub-components. It trades some customization for less development time. We gradually expand our use-case support.

• Not a complete UI library. For a complete collection of lower level components, please see the Ionic Framework component library. Your Maincode UI theming will automatically theme any Ionic component!

• Usable with most React.js frameworks. The components even support server side rendering in Next.js with the use of dynamic imports.

• An Ionic extension. It provides utilities for some things which are usually difficult in Ionic apps, such as our dark mode context and scrollbar styling helper.

Getting Started

Read the Getting Started tutorial or follow the steps below:

!Note that the library is currently not fully compatible with React v. 17+, due to the React Live v. 2.3.0 library's incompatibility with React v. > 16.14. The means our LiveCodeEditor component cannot be used with React v. 17. For more information, follow this issue which can be monitored for updates.

⏳ Installation

npm install --save maincode-ui

🎉 Usage

For usage on all components, please see the complete component documentation.

The code below is the minimum needed to get started with a Maincode UI app, and spawning a CopyArea component identical to the first command on this page.

!Note that the stylesheets need only be imported once for each app, not for every component.

import React from 'react';
import { CopyArea } from 'maincode-ui';

// > Ionic styles omitted for breviety..

/** Maincode UI stylesheets. */
import 'maincode-ui/dist/index.css'; // All the component specific styles.
import 'maincode-ui/styles/theme.css'; // The default theme variables. See the "themes" section for customization.

const ExampleApp: React.FC = () => {
  return <CopyArea command={'npm install --save maincode-ui'} />;
};

The app will also need most of the styling from Ionic as well to work correctly. Add the Ionic style imports at the indicated location in the above example. The imports are:

/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';

/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';

/* Optional CSS utils that can be commented out */
import '@ionic/react/css/padding.css';
import '@ionic/react/css/float-elements.css';
import '@ionic/react/css/text-alignment.css';
import '@ionic/react/css/text-transformation.css';
import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';

Theming

The maincode-ui/styles/theme.css file provides a base theme. To customize the theme you can overwrite relevant CSS variables. We generally use the Ionic theme variable names, with a few Maincode UI additions.

To do this, create a new theme.css file, and assign values to the CSS variables described in the Ionic documentation.

Besides the Ionic variables, we also provide the Maincode UI specific variables described in our theming documentation.

Styling the scrollbar

It is normally difficult to apply scrollbar styles to Ionic applications (see their issue).

We provide a helper to style the scrollbar. It can be used after the app is mounted:

import React, { useEffect } from 'react';
import styleScrollbar from 'maincode-ui';

const App: React.FC = () => {
  useEffect(() => {
    styleScrollbar();
  }, []);

  return <p>Some app</p>;
};

!Note that this helper is called automatically when the ThemeContext changes, allowing for separate dark mode scrollbar styling. If you are using our ThemeContext, you don't have to import the script.

The look of the scrollbar can be modified as described in our theming documentation.

Dark mode

The library provides a context ThemeContext to manage and apply the dark and light mode themes.

Enable it by applying the context on the root element of your app as shown below.

import { ThemeContext } from 'maincode-ui';

//> stylesheets and other imports omitted for brievity..

const App: React.FC = () => {
  const theme = useContext(ThemeContext);

  return <div className={theme?.themeName}>my app!</div>;
};

And wrap the app in the ThemeProvider for the context as shown below.

ReactDOM.render(
  <ThemeProvider>
    <App />
  </ThemeProvider>,
  document.getElementById('root')
);

Alternatively, the dark mode of the library components can be partially controlled by toggling the classnames "light" and "dark" on the body element.

You can customize your dark mode theme by setting values for any CSS variable in your custom theme file.

The variables must be on the body.dark element, and also apply for .md body.dark and .ios body.dark elements. The reason is that dark mode is set as a classname on the body element with values "light" or "dark".

body.dark,
.ios body.dark,
.md body.dark {
  --ion-text-color: #bdbddd;
  --ion-color-primary: #dd7500 !important;
  ...;
}

This approach allows you to use variables like --ion-text-color in your app, and have the targeted element automatically adapt to dark mode.

Setting and reading dark mode manually

The provided ThemeContext allows you to toggle and read the state of the app theme. This is useful when making "toggle" buttons for dark mode, or adapting components dynamically based on theme changes.

It can be used as shown in the example below:

import { ThemeContext } from 'maincode-ui';

const MyComponent: React.FC = () => {
  const theme = useContext(ThemeContext);

  return (
    <div>
      <h1>my {theme?.themeName} mode component!</h1>
      <button onClick={theme?.toggleTheme}> toggle light/dark mode for the entire app</button>
    </div>
  );
};

!Note that the ThemeContext also sets the mode in the browsers localStorage under the themeName key, automatically saving the clients' selected theme and loading it by default on future visits.

Styling system

Maincode UI offer a lot of styling through pre-defined classnames.

• This is entirely inspired by Tailwind CSS and can be seen as a less advanced subset of Tailwind.

• It can be exchanged for Tailwind CSS if you want additional classnames or smart functionality such as purging.

• In case you are using Tailwind CSS, you don't have to import our tail-generics.

Here is an example of how to utilize the generic classes when styling and layouting your app!

<div className='flex flex-col p-1 glass-bg rounded shadow-md'>
  <p className='bold'>A bold styled p</p>
  <p className='color-bg'>Another styled p</p>
</div>

Contributing

Like this project?

We always like to participate in interesting projects, and we love to help you overcome any difficulties with our library.

If you have feedback or would like to work with is, please don't hesitate to contact us at [email protected] or [email protected]

Extending the code base

Please see the development details below to get started with the code base.

Setting up

The repository contains two things. The UI library's modules in the root, and the documentation react app in the /documentation-app folder.

To get started, first run npm install in both folders.

Run npm start in the root folder to actively recompile the library code on changes. Run the same command in the documentation app to launch the app and listen to library component changes with live reloading.

Library structure

Please notice how the logic is grouped in the following folder structure:

/styles contain the different stylesheets with their own logical CSS overwrites. See the usage example for an explanation on the difference.

/src/components contains sub-folders for each category of components offered in the library, and another level of sub-folders for each component in the category.

/documentation-app/src/pages contain all the documentation content for each component. Please keep this updated when contributing new components.

/documentation-app/src/structure assembles all the documentation pages into our navigation, route and layout generators. Documentation entries must be added here to appear in the webapp.

Testing

To run tests, use npm run test.

The source for the tests are located in the /tests directory.

The tests should cover at least all exposed methods in the toolkits.

License

BSD 3-Clause License © MarkKragerup