Shared Web Components with theming for use across HOTOSM tools.
📖 Documentation:
https://ui.hotosm.org
🖥️ Source Code:
https://github.com/hotosm/ui
🎯 Roadmap / Tasks: https://github.com/orgs/hotosm/projects/37/views/3
This repository contains advice on how to use the WebAwesome Web Components library, references to the HOTOSM style guide, and a few 'wrapper' components to assist development:
- Reduced code duplication across HOT tools (we repeat a lot!)
- Simplified developer experience to create a HOT app.
- Reasonably consistent theming and style across tools.
The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance. It should include a minimal number of components, such as:
- Header, including auth flows (OSM, Google) and login info.
- Sidebar with links to extra resources.
- Footer with links.
Current HOTOSM UI version used: 0.3.1-b5
Current WebAwesome version used: 3.0.0-beta.1
pnpm install "@awesome.me/[email protected]"Note
It's important to pin the version of web awesome used to the version in this library, to avoid any conflicts and incompatibilities between components.
pnpm install "@hotosm/ui"In your index.html or equivalent frontend root, add the following classes
to your <html> block:
<!DOCTYPE html>
<html class="wa-theme-default wa-palette-hotosm wa-brand-red wa-neutral-gray
wa-success-cyan wa-warning-yellow wa-danger-orange">
<head>
xxx
</head>
<body>
xxx
</body>
</html>Important
These classes determine the colour usage for different component variants, and probably should not be changed!
And import the required styles in your main.ts or equivalent (we import from package
rather than CDN, to allow the bundler to work it's CSS tree-shaking magic).
import '@hotosm/ui/dist/style.css';If you wish to use any of the variables in hot.css manually, you can reference
them as variables like so:
/* In your CSS file */
some-param: var(--hot-some-param);
/* See all variables in the `theme/hot.css` file */Import each component individually into your code:
<script>
import '@hotosm/ui/dist/components/header/header.js';
</script>
<hot-header
param1=""
param2=""
>
</hot-header>If you are working directly in HTML, or other ways without a configured bundler, you can import all the components as a bundle, as use them like so:
<script>
import '@hotosm/ui/dist/style.css';
import '@hotosm/ui/dist/hotosm-ui';
</script>
<hot-logo><hot-logo>
<hot-button variant="primary">Click me!</hot-button>Import in the same way as the bundler example above, except events are bound to slightly differently:
<hot-button
size='small'
variant='text'
disabled={currentIndex <= 0}
onClick={() => {
console.log('do stuff');
}}
>
</hot-button>HOT UI is developed in TypeScript, using Lit and @lit/react.
Primarily we want to have:
- Low level components exported from the Shoelace web component library, simply re-exported with our default styling / CSS overrides.
- A few composite components (header, sidebar, etc):
- Consistent styling across most of our tools where it counts.
- Reduction in duplicated logic, such as user management, OAuth login, etc.
- Improved developer experience, reduced development time for new tools, while maintaining consistency in look and feel of applications.
- Clone the project
git clone [email protected]:hotosm/ui.git - Install dependencies
pnpm install - Run the storybook
pnpm run dev - Write code!
For styling, check /theme:
hot.csshas a HOT theme, used across HOT componentshot-sl.csshas a Shoelace theme, re-defining styles variables
HOT UI is free and open source software! you may use any HOT UI project under the terms of the GNU Affero General Public License (AGPL) Version 3.