Forge is a framework-agnostic library of Web Components adhering to W3C Web Component Spec and the Tyler Forge™ Design System. Originally derived from Google's Material Components Web project, this project aims to create a consistent UI/UX across applications regardless of choice in front-end frameworks. Theming is a core part of the library such that competing design objectives can be achieved while still providing UI/UX cohesion across product catalogs. Please visit the Tyler Forge™ Design System website for additional guidance and documentation.
As noted above, Forge components are framework-agnostic. If you haven't used Web Components before just think of them as new HTML elements that the browser knows
about, just like any old <div>, <button>, <input>... etc. This means that any framework can already work with them natively without any work on your end.
The caveat to this is that many custom Web Components are enhanced to allow for more complex data (arrays and objects) to be provided, as well as custom event names to get notified about changes within the element. This is where framework adapter libraries can help to make the usage more seamless.
Forge provides the following framework adapters:
Keep in mind that these adapter libraries are not required by any means. They are only provided to make usage for certain components feel more native for developers using these frameworks.
The component library is distributed on npm and as static assets on via CDN.
To develop locally, simply run the following commands from the root of the project after cloning:
npm install
npm startFor more information about developing locally, see the dev site README.
The Forge component library follows semver to ensure that consumers can rely on a standard versioning scheme when using Forge components.
To install the library from npm:
npm install @tylertech/forgeYou can then import the component definition functions to register them with the browser:
import { defineTextFieldComponent, defineButtonComponent } from '@tylertech/forge';
defineTextFieldComponent();
defineButtonComponent();Note: the components are actually self-defining, but without something in your application referencing those components they could be left out during bundling. These definition functions ensure that the components are bundled within your application.
The @tylertech/forge package follows the following format:
-
dist/: Contains all pre-built static distribution sources.-
<component name>/: pre-built CSS stylesheets for specific components. -
esm/: Contains the bundled ESM JavaScript sources (includes dependencies as code-split chunks) -
forge-core.css: The optional Forge core stylesheet. Typically useful when using the<forge-scaffold>for your outer page layout. -
forge-dark.css: The default Forge dark theme (must be loaded afterforge.css). -
forge.css: The pre-built Forge global stylesheet. Contains all required component-specific stylesheets. You should prefer to load individual stylesheets instead of this global stylesheet in production.
-
-
esm/: Contains the unbundled ESM JavaScript sources as the main entry to the package (includes bare module specifiers) -
styles/: Contains all Sass stylesheets as a copy directly from the library. -
LICENSE: The Apache 2.0 license. -
package.json: The package specification. -
README.md: This README.md file.
Forge expects a global stylesheet to be loaded to configure the theme and typography globally across your application, and some components may require additional css.
@use '@tylertech/forge/dist/forge.css';The forge.css file contains other stylesheets that you may or may not need. We recommend you only include the stylesheets you need in your application:
/// Optionally include a minimal base set of styles commonly used with Forge-based applications
@use '@tylertech/forge/dist/forge-core.css';
/// Include the theme and typography styles
@use '@tylertech/forge/dist/theme/forge-theme.css';
@use '@tylertech/forge/dist/typography/forge-typography.css';
/// Include styles for <forge-button> elements
@use '@tylertech/forge/dist/button/forge-button.css';Additionally, apply the forge-typography class to a root element (typically the <body>):
<body class="forge-typography">The Forge CDN can provide components directly on demand.
As an example, the text-field and button components can be loaded directly like this:
<!-- Optionally include a minimal base set of styles commonly used with Forge-based applications -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/forge-core.css">
<!-- Always include the theme and typography styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/theme/forge-theme.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/typography/forge-typography.css">
<!-- Some components (such as button) require the use of a global stylesheet (for now) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/button/forge-button.css">
<!-- Load the ES modules JavaScript for each component you need -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/esm/text-field/index.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@tylertech/forge@2.0.0/dist/esm/button/index.js"></script>Now the text-field and button components can be used anywhere in the DOM:
<forge-text-field>
<label for="input">Label</label>
<input type="text" id="input" />
</forge-text-field>
<forge-button type="raised">
<button type="button">Button</button>
</forge-button>Don't forget to also add the forge-typography class to the <body> element to ensure your application inherits the default typography styles:
<body class="forge-typography">Please create a GitHub issue with any questions and we'll be glad to help!