AgnosticUI Component Library #

AgnosticUI is a library of UI component primitives that work in React, Vue, Svelte, and Angular (experimental)!

Just want to see it in action? #

View in CodeSandbox View in Stackblitz

Installation #

Before you setup AgnosticUI, we recommend you first have a look at the browsers supported list.

NPM #

This section will discuss using AgnosticUI via package manager installation and ES modules imports. In your project's top-level directory install the AgnosticUI package of your choice:

npm install agnostic-PACKAGE # or yarn add agnostic-PACKAGE

For example, to install the agnostic-react package you'd do:

npm install agnostic-react # or yarn add agostic-react

The currently available framework packages are: agnostic-react, agnostic-vue, agnostic-angular, and agnostic-svelte.

Follow the appropriate framework-specific instructions below…

React #

The agnostic-react package has a few peer dependencies which you'll need to npm install:

  uuid: 'uuid',
  react: 'React',
  'react-dom': 'ReactDOM',
...

These can be installed into your project with: npm i uuid react react-dom

Imports #

To use the agnostic-react package in your project do the following:

• Step 1: Import AgnosticUI's common CSS

import "agnostic-react/dist/common.min.css";

• Step 2: Import the AgnosticUI component-specific CSS

import "agnostic-react/dist/esm/index.css";

• Step. 3: Import the AgnosticUI component(s) you'd like to use

import { Alert, Button } from "agnostic-react";

• Step 4: Use

const message = 'Alerts should be used for timely information.';

export const YourComponent = () => (
  <>
    <Alert>{message}</Alert>
    <Button mode="primary">Go</Button>
  </>
);

Vue 3 #

AgnosticUI supports Vue 3 only!

To use the agnostic-vue package in your project do the following:

• Step 1: Import AgnosticUI's common CSS

<script>
import 'agnostic-vue/dist/common.min.css'
// ...
</script>

• Step 2: Import the AgnosticUI component-specific CSS

<script>
// ...
import "agnostic-vue/dist/index.css";
</script>

• Step. 3: Import the AgnosticUI component(s) you'd like to use and declare component prop

<script>
// ...
import { Alert } from "agnostic-vue";
export default {
  name: "AlertExample",
  components: {
    Alert,
  },
};
</script>

• Step 4: Use in your template

<template>
  <Alert
    isBorderLeft
    type="info"
  >Example alert</Alert>
</template>

Angular (Experimental) #

To use the agnostic-angular package in your project do the following:

Step 1: Import AgnosticUI's common CSS

In your Angular configuration (likely angular.json) ensure you're including the common AgnosticUI styles. Here's example if you've used nx:

    "yourapp": {
      ...
      "architect": {
        "build": {
          "options": {
            ...
            "styles": ["agnostic-angular/common.min.css"],

Step. 2: Add AgnosticUI's AgModule module:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AgModule } from 'agnostic-angular';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AgModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

Step. 3: Now you can use AgnosticUI in your Angular components:

import { Component } from '@angular/core';

@Component({
  selector: 'your-component',
  template: `<ag-avatar text="AB"></ag-avatar>`,
})
export class YourComponent {}

You can also find an example application configured in AgnosticUI's Angular workspace at agnostic-angular/angular.json, and view its main app template. See the Angular package's Getting Started instructions to run the example application locally.

Svelte #

To use the agnostic-svelte package in your project do the following:

• Step 1: Import AgnosticUI's common CSS

<script>
import 'agnostic-svelte/css/common.min.css';
// ...
</script>

• Step. 2: Import the AgnosticUI component(s) you'd like to use and declare component prop

<script>
// ...
import { Button } from 'agnostic-svelte';
</script>

• Step 3: Use in Svelte template

<body>
  <!-- ... -->
  <Button mode="primary">Go</Button>
  <!-- ... -->

I've placed some additional agnostic-svelte-based experiments on my blog which may also prove helpful.

Platform HTML, CSS, & JavaScript #

If your project does not use a JavaScript framework but prefers platform-based HTML, CSS, and JavaScript, you may wish to use AgnosticUI to apply global CSS classes. This is similar to how you may have done before using a popular CSS library like Bootstrap or Foundation). To use AgnosticUI in this way simply link the common CSS and component CSS as follows:

...
<link rel="stylesheet" href="agnostic/common.min.css">
<link rel="stylesheet" href="agnostic/components.min.css">
</head>
<body>

With that, you will be able to apply AgnosticUI's CSS classes globally to your markup:

...
<button class="btn btn-primary" onClick="e => doSomething(e)">Go</button>

Below is a video introduction that shows an example of setting up a skeleton page to use agnostic-css as described above in case you prefer that approach…

CSS #

The above directions will get you started using AgnosticUI in the framework of your choice and include the common CSS as well. However, you may also want to utilize some basic cascading font styles on your body or .root application container. We leave specifics to your discretion, but this may help you get started:

.root {
  font-family: var(--agnostic-font-family-body);
  font-size: var(--agnostic-body);
  color: var(--agnostic-font-color);
  -webkit-font-smoothing: antialiased;
  line-height: 1.5;
}

Browsers Supported #

The following is the current .browserlistrc configuration as per the Can I Use database:

last 2 versions and > 2%
last 2 versions
Firefox ESR
not dead
not IE 11
maintained node versions
not op_mini all

Why AgnosticUI doesn't support IE11 #

We use CSS logical properties which support direction-agnostic writing modes (e.g. horizontal-tb, vertical-rl, etc.) See MDN writing-mode docs to learn more.

Browser (UMD) #

UMD (and CJS) builds are already available for each package. However, the use of CDN hosted UMD builds via <script> tags is currently unreliable (Vue 3's Boolean props don't take, CSS Modules don't load properly, etc.). We will continue to troubleshoot these issues and report back when there's been some progress made. In the meantime, we suggest you follow the ES module setup as described above.