HOT Shared UI¶
Shared Web Components with theming for use across HOTOSM tools.
📖 Documentation:
https://hotosm.github.io/ui/
🖥️ Source Code:
https://github.com/hotosm/ui
🎯 Roadmap / Tasks: https://github.com/orgs/hotosm/projects/37/views/3
Shared UI Components with HOT Theming¶
This repository contains HOT themed UI components to reduce code duplication and simplify the lives of developers needing to prototype and develop well designed web applications quickly.
They are available as Web Components with support for usage in almost all modern web frameworks.
The main goal of this project is not to re-invent the wheel, or add an extra burden of development and maintenance.
Quick start¶
There are two options: NPM and Components Bundle.
NPM¶
Appropriate for applications that have installable dependencies
npm install @hotosm/ui
Import the library in your project and use the components.
<script>
import '@hotosm/ui/dist/style.css';
import '@hotosm/ui/dist/hotosm-ui.js';
</script>
<hot-logo><hot-logo>
React¶
import { Logo } from '@hotosm/ui/components/react';
<Logo />
Components Bundle¶
- This is the compiled JavaScript bundle generated from the TypeScript code.
- The components require no additional dependencies and are minified.
Appropriate for HTML / Markdown / HTMX.
<link
rel="stylesheet"
href="https://s3.amazonaws.com/hotosm-ui/latest/style.css"
/>
<script
type="module"
src="https://s3.amazonaws.com/hotosm-ui/latest/dist/hotosm-ui.js"
></script>
<hot-logo></hot-logo>
Using Extra Shoelace Components¶
The HOT UI library contains many composite components, such as headers, sidebars, tracking banners, etc, and does not re-invent the wheel for low-level components.
Shoelace is an UI library that is exported directly from @hotosm/ui
.
To access the low-level components, such as buttons, dropdowns, modals, etc, simply import the component of the same name from the [Shoelace docs] (https://shoelace.style):
import '@hotosm/ui/components/button/button';
<hot-button disabled variant="secondary">Can't Click Me</hot-button>
React Shoelace Wrappers¶
import { Button } from '@hotosm/ui/components';
<Button disabled variant="secondary">Can't Click Me</Button>
Examples¶
You can found examples for HTML and also all common frameworks
(React, Svelte, Vue) under /examples
.
Development¶
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.
How to contribute¶
- Clone the project
git clone git@github.com:hotosm/ui.git
- Install dependencies
pnpm install
- Run the storybook
pnpm run dev
- Write code!
There's also a React storybook that you can use for testing:
- Run the React storybook
pnpm run dev-react
For styling, we have 2 important files under /theme
:
hot-sl.css
has a Shoelace theme, re-defining some variableshot.css
has custom styles for eveything else, specially composited components
License¶
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.