Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@microsoft/fast-element

Microsoft640.5kMIT2.9.1TypeScript support: included

A library for constructing Web Components

readme

FAST Element

License: MIT npm version

The fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.

Installation

From NPM

To install the latest fast-element library using npm:

npm install --save @microsoft/fast-element

Within your JavaScript or TypeScript code, you can then import library APIs like this:

import { FASTElement } from '@microsoft/fast-element';

From CDN

A pre-bundled script that contains all APIs needed to build web components with FAST Element is available on CDN. You can use this script by adding type="module" to the script element and then importing from the CDN.

<!DOCTYPE html>
<html lang="en">
    <head>
        <script type="module">
          import { FASTElement } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-element/dist/fast-element.min.js";

          // your code here
        </script>
    </head>
    <!-- ... -->
</html>

The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:

<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-element@1.6.2/dist/fast-element.min.js"></script>

:::note For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL. :::

:::tip Looking for a quick guide on building components? Check out our Cheat Sheet. :::

changelog

Change Log - @microsoft/fast-element

2.9.1

Tue, 16 Dec 2025 21:27:19 GMT

Patches

2.9.0

Mon, 08 Dec 2025 19:47:51 GMT

Minor changes

2.8.5

Tue, 02 Dec 2025 21:46:59 GMT

Patches

2.8.4

Mon, 01 Dec 2025 18:46:00 GMT

Patches

2.8.3

Wed, 12 Nov 2025 20:41:54 GMT

Patches

2.8.2

Fri, 31 Oct 2025 20:45:55 GMT

Patches

2.8.1

Tue, 21 Oct 2025 16:17:27 GMT

Patches

2.8.0

Mon, 13 Oct 2025 00:37:08 GMT

Minor changes

2.7.0

Wed, 20 Aug 2025 20:57:02 GMT

Minor changes

2.6.0

Wed, 06 Aug 2025 07:15:13 GMT

Minor changes

2.5.0

Wed, 16 Jul 2025 22:43:52 GMT

Minor changes

2.4.1

Fri, 30 May 2025 05:02:03 GMT

Patches

2.4.0

Fri, 23 May 2025 23:52:29 GMT

Minor changes

2.3.0

Mon, 05 May 2025 00:33:41 GMT

Minor changes

2.2.1

Wed, 16 Apr 2025 15:53:12 GMT

Patches

2.2.0

Mon, 24 Mar 2025 18:26:13 GMT

Minor changes

2.1.0

Thu, 13 Feb 2025 17:34:08 GMT

Minor changes

2.0.1

Wed, 11 Dec 2024 19:53:31 GMT

Patches

2.0.0

Mon, 19 Aug 2024 22:04:19 GMT

Major changes

Changes

2.0.0-beta.26

Fri, 18 Aug 2023 00:04:40 GMT

Changes

2.0.0-beta.25

Sat, 12 Aug 2023 00:26:36 GMT

Changes

2.0.0-beta.24

Fri, 16 Jun 2023 18:17:12 GMT

Changes

2.0.0-beta.23

Tue, 28 Mar 2023 22:14:10 GMT

Changes

2.0.0-beta.22

Sat, 11 Mar 2023 00:09:48 GMT

Changes

2.0.0-beta.21

Tue, 14 Feb 2023 04:02:35 GMT

Changes

2.0.0-beta.20

Wed, 11 Jan 2023 22:07:47 GMT

Changes

2.0.0-beta.19

Fri, 02 Dec 2022 01:18:22 GMT

Changes

2.0.0-beta.18

Tue, 15 Nov 2022 02:40:34 GMT

Changes

2.0.0-beta.17

Tue, 01 Nov 2022 23:26:26 GMT

Changes

  • fix: prevent circular reference errors when stringifying DOM nodes controlled by FAST's rendering engine (roeisenb@microsoft.com)

2.0.0-beta.16

Fri, 28 Oct 2022 20:44:44 GMT

Changes

2.0.0-beta.15

Tue, 25 Oct 2022 20:24:32 GMT

Changes

2.0.0-beta.14

Fri, 14 Oct 2022 18:26:11 GMT

Changes

2.0.0-beta.13

Mon, 10 Oct 2022 20:28:02 GMT

Changes

2.0.0-beta.12

Thu, 06 Oct 2022 23:21:20 GMT

Changes

2.0.0-beta.11

Wed, 05 Oct 2022 23:26:01 GMT

Changes

2.0.0-beta.10

Mon, 03 Oct 2022 23:44:38 GMT

Changes

2.0.0-beta.9

Wed, 28 Sep 2022 20:45:51 GMT

Changes

2.0.0-beta.8

Tue, 27 Sep 2022 22:31:52 GMT

Changes

2.0.0-beta.7

Fri, 23 Sep 2022 22:53:27 GMT

Changes

2.0.0-beta.6

Thu, 01 Sep 2022 21:53:34 GMT

Changes

2.0.0-beta.5

Thu, 18 Aug 2022 20:46:10 GMT

Changes

2.0.0-beta.4

Mon, 18 Jul 2022 21:10:01 GMT

Changes

2.0.0-beta.3

Wed, 22 Jun 2022 20:17:50 GMT

Changes

2.0.0-beta.2

Wed, 15 Jun 2022 17:41:10 GMT

Changes

2.0.0-beta.1

Wed, 01 Jun 2022 17:53:14 GMT

Changes

  • DOM - Tree Walker methods are no longer used and are thus removed. The API for removing child nodes has been removed as well since it was only used in one place and could be inlined. The helper createCustomAttributePlaceholder() no longer requires an attribute name. It will be uniquely generated internally. (roeisenb@microsoft.com)
  • class - Bindings to class are now more nuanced. Binding directly to class will simply set the className property. If you need to bind to class knowing that manual JS will also manipulate the classList in addition to the binding, then you should now bind to :classList instead. This allows for performance optimizations in the simple, most common case. (roeisenb@microsoft.com)
  • Behavior and ViewBehavior - Behavior now requires an ExecutionContext for unbind. Behaviors can be used for elements or views. ViewBehavior has been introduced for use exclusively with views, and provides some optimization opportunities. (roeisenb@microsoft.com)
  • RefBehavior has been replaced with RefDirective. The directive also implements ViewBehavior allowing a single directive instance to be shared across all template instances that use the ref. (roeisenb@microsoft.com)
  • Removed SlottedBehavior and ChildrenBehavior have been replaced with SlottedDirective and ChildrenDirective. These directives allow a single directive instance to be shared across all template instances that use the ref. (roeisenb@microsoft.com)
  • Removed AttachedBehaviorHTMLDirective and AttachedBehaviorType since they are no longer used in the new directive/behavior architecture for ref, slotted, and children. (roeisenb@microsoft.com)
  • Renamed Notifier#source to Notifier#subject to align with other observable terminology and prevent name clashes with BindingObserver properties. (roeisenb@microsoft.com)
  • feat: create unified API for parsing markers (roeisenb@microsoft.com)
  • allow null values in attributeChangedCallback (nicholasrice@users.noreply.github.com)
  • feat: add splice strategies for array observation (roeisenb@microsoft.com)
  • feat: handle existing shadow roots when upgrading (roeisenb@microsoft.com)
  • fix: enable safer type inference on the repeat helper (roeisenb@microsoft.com)
  • Set prerelease version (nicholasrice@users.noreply.github.com)
  • refactor: separate update queue from DOM and fix architectural layers (roeisenb@microsoft.com)
  • feat: aspected html directive exposes metadata (roeisenb@microsoft.com)
  • HTMLDirective - The targetIndex: number property has been replaced by a targetId: string property. The createBehavior method no longer takes a target Node but instead takes a BehaviorTargets instance. The actual target can be looked up on the BehaviorTargets instance by indexing with the targetId property. (roeisenb@microsoft.com)
  • compileTemplate() - Internals have been significantly changed. The implementation no longer uses a TreeWalker. The return type has change to an HTMLTemplateCompilationResult with different properties. (roeisenb@microsoft.com)
  • refactor: move template/style resolution to lazy getter (roeisenb@microsoft.com)
  • refactor: enable pluggable template compiler for SSR scenarios (roeisenb@microsoft.com)
  • feat: enable pluggable style handling strategies (roeisenb@microsoft.com)
  • fix(fast-element): do not notify splices for changes pre-subscription (roeisenb@microsoft.com)
  • feat: new directive registration/identification model (roeisenb@microsoft.com)
  • fix: prevent duplicative array observation patch (roeisenb@microsoft.com)
  • Adds Aspect as public export (nicholasrice@users.noreply.github.com)
  • feat: expose official Markup and Parser APIs (roeisenb@microsoft.com)
  • refactor: refine binding mode types (roeisenb@microsoft.com)
  • feat: add two-way binding (roeisenb@microsoft.com)
  • fix: defend against for/in use on arrays (roeisenb@microsoft.com)
  • fix: merge bug related to moved APIs (roeisenb@microsoft.com)
  • feat: enable multiple instances of fast-element on a page at once (roeisenb@microsoft.com)
  • Upgrade TypeScript (nicholasrice@users.noreply.github.com)
  • enumerate fast-element package as a ES module package (nicholasrice@users.noreply.github.com)
  • feat: enable array length observation (roeisenb@microsoft.com)
  • feat: add utilities and hooks, and change exports (roeisenb@microsoft.com)
  • refactor: new design for execution context (roeisenb@microsoft.com)
  • chore: fast-element package and build modernization (roeisenb@microsoft.com)
  • feat: new CSSDirective design (roeisenb@microsoft.com)
  • chore: configure fast-element for internal stripping (roeisenb@microsoft.com)
  • feat: enable synchronous dom updates for SSR (roeisenb@microsoft.com)
  • refactor: extract polyfill and polyfill-like code to an optional module (roeisenb@microsoft.com)
  • feat: add warn/error message infrastructure (roeisenb@microsoft.com)
  • View and HTMLView - Type parameters added to enable strongly typed views based on their data source. The constructor of HTMLView has a new signature based on changes to the compiler's output. Internals have been cleaned up and no longer rely on the Range type. (roeisenb@microsoft.com)
  • ElementViewTemplate, SyntheticViewTemplate, and ViewTemplate - Added type parameters throughout. Logic to instantiate and apply behaviors moved out of the template and into the view where it can be lazily executed. Removed the ability of the render method to take a string id of the node to render to. You must provide a node. (roeisenb@microsoft.com)

1.10.2

Tue, 24 May 2022 07:10:02 GMT

Patches

1.10.1

Tue, 03 May 2022 07:15:44 GMT

Patches

1.10.0

Wed, 27 Apr 2022 07:21:09 GMT

Minor changes

1.9.0

Wed, 06 Apr 2022 07:12:42 GMT

Minor changes

1.8.0

Tue, 08 Mar 2022 07:12:45 GMT

Minor changes

1.7.2

Fri, 25 Feb 2022 17:09:32 GMT

Patches

1.7.1

Thu, 24 Feb 2022 22:21:55 GMT

Patches

1.7.0

Sun, 23 Jan 2022 07:13:56 GMT

Minor changes

1.6.2

Sun, 31 Oct 2021 07:17:45 GMT

Patches

1.6.1

Wed, 13 Oct 2021 22:45:16 GMT

Patches

1.6.0

Fri, 08 Oct 2021 19:53:11 GMT

Minor changes

1.5.1

Wed, 08 Sep 2021 07:16:17 GMT

Patches

1.5.0

Fri, 27 Aug 2021 14:14:26 GMT

Minor changes

1.4.2

Thu, 26 Aug 2021 07:17:43 GMT

Patches

1.4.1

Wed, 28 Jul 2021 07:17:22 GMT

Patches

1.4.0

Fri, 21 May 2021 17:48:08 GMT

Minor changes

1.3.0

Wed, 19 May 2021 23:37:36 GMT

Minor changes

1.0.2 (2021-04-06)

Bug Fixes

  • ensures proper re-observation and notification of a disconnected BindingObserver (#4477) (e315a69)

1.0.1 (2021-03-16)

Bug Fixes

  • ensure embedded templates dispose correctly (#4432) (cb8ae10)

1.0.0 (2021-03-06)

  • refactor(fast-element)!: rename Directive, disambiguate types, and reorganize (#4414) (a96d364), closes #4414

Features

  • adds CSSDirective for use with the css tagged template literal (#4383) (6928afa)

BREAKING CHANGES

  • rename Directive and other types to disambiguate

0.22.2 (2021-02-08)

Note: Version bump only for package @microsoft/fast-element

0.22.1 (2021-02-08)

Note: Version bump only for package @microsoft/fast-element

0.22.0 (2021-01-30)

Bug Fixes

  • increase sophistication of behavior binding and unbinding (#4288) (9c24ee6)
  • repeat: observe arrays after unbound then rebound (#4211) (cec8e69)

Features

  • add support for attachment test to ElementStyles (#4289) (df6f765)

0.21.1 (2020-12-16)

Note: Version bump only for package @microsoft/fast-element

0.21.0 (2020-12-02)

Features

0.20.0 (2020-11-19)

Bug Fixes

  • fast-element: ensure all nodes removed in repeat when array emptied (#4073) (cacfefe)
  • fast-element: remove mergeSplice array length cache (#4067) (751eef8)

Features

  • add select component (#4074) (6984027)
  • convert FormAssociated to a constructable function (#4115) (da8d54b)
  • makes Controller.isConnected an observable property (#4093) (3d49aa2)
  • fast-element: introduce NamedTargetDirective for extensibility (#4079) (c93bc26)
  • support HTMLStyleElement from Controller.addStyles and Controller.removeStyles (#4043) (cf20187)

0.19.1 (2020-10-14)

Note: Version bump only for package @microsoft/fast-element

0.19.0 (2020-09-28)

Bug Fixes

  • fast-element: enable subtree observation in the children decorator (#3945) (c69c7d9)

Features

  • fast-element: enable parent context references in repeat scenarios (#3948) (0b2234b)

0.18.0 (2020-09-10)

Bug Fixes

  • fast-element: better global support for older browsers (#3864) (61e85d8)
  • fast-element: workaround for adoptedStyleSheets Chromium bug (#3838) (1b6570a)

Features

  • fast-element: enable custom element to accept a styles array (#3871) (ae611a9)

0.17.0 (2020-08-27)

Bug Fixes

  • fast-element: add globalThis polyfill to fix trustedTypes polyfill (#3797) (e848800)
  • fast-element: do not remove user comments when compiling templates (#3786) (0478709)
  • fast-element: observable callbacks on sub-classes should be invoked (#3768) (969d5dd)

Features

  • fast-element: improve trustedTypes to not use globalThis (#3784) (5eca0a8)

0.16.0 (2020-08-13)

Bug Fixes

Features

  • fast-element: move template instance timing and enable dynamic templates and styles (#3621) (2e73088)

0.15.2 (2020-07-31)

Note: Version bump only for package @microsoft/fast-element

0.15.1 (2020-07-23)

Bug Fixes

  • rollup minify selectors should retain spaces (#3524) (cbdfc45)

0.15.0 (2020-07-14)

Bug Fixes

  • fast-element: style element styles should work with the document (#3489) (d288390)

Features

  • simplify rollup configs and compress tagged template literals (#3452) (7533e92)
  • update typescript version and remove utility types dependencies for react packages (#3422) (09d07b5)

0.14.0 (2020-07-02)

Bug Fixes

  • fast-element: do not notify when binding observer is disconnected (#3418) (dbf3093)

Features

  • fast-element: support bindings and observables with volatile dependencies (#3402) (a00a907)

0.13.0 (2020-06-26)

Bug Fixes

  • fast-element: default event handler behavior should be no capture (#3337) (a59e4df)
  • fast-element: export missing elements filter helper (#3331) (46de565)

Features

  • fast-element: enable CSSStyleSheet and string to be used as styles (#3345) (70e2f7f)
  • fast-element: expand element filter to support selectors (#3374) (f275366)

0.12.0 (2020-06-17)

Features

  • fast-element: enable children and slotted filters (#3323) (224df54)

0.11.0 (2020-06-15)

Bug Fixes

  • correct anchor and button stylesheets (#3308) (78feda2)
  • fast-element: generalize value converter and move out of beta (#3267) (14706c9)
  • fast-element: seal the default execution context (#3268) (131cacb)
  • corrects behavior of style removal (#3261) (e37b7ab)

Features

  • fast-element: enable repeat template binding (#3287) (00129bc)

0.10.1 (2020-06-09)

Note: Version bump only for package @microsoft/fast-element

0.10.0 (2020-06-05)

Features

  • fast-element: add content composition (#3182) (26c59ea)
  • website: new docusaurus v2 setup with launch toc configuration (#3159) (f12ba16)

0.9.0 (2020-05-18)

Bug Fixes

  • fast-element: every third subscriber not registered (#3086) (bd26083)
  • fast-element: html helper should handle literal and directive interpolated together (#3106) (627f06c)
  • add exports that were removed during circular reference refactor #3038 (eb1cb91)

Features

  • fast-element: more granular content compilation with tests (#3127) (c96fef2)
  • web-components: new build/test/docs setup (#3156) (51d909a)

0.8.1 (2020-04-29)

Bug Fixes

  • removes circular dependencies from web-component packages (#3037) (0f84942)

0.8.0 (2020-04-27)

Bug Fixes

  • fast-element: attr bindings preserved during upgrade (#3010) (e9b14cc)

Features

  • fast-element: add a render method to templates for pure templating (#3018) (c4ac6b2)

0.7.0 (2020-04-22)

Bug Fixes

Features

0.6.0 (2020-04-10)

Bug Fixes

  • fast-element: always reflect latest value to attribute (#2903) (48cca59)
  • fast-element: batch attr reflect (#2885) (e863752)
  • fast-element: ensure node exists when checking if it's a marker (#2876) (ae656b8)
  • fast-element: only use Range for batch disposal (#2901) (7e5bf5c)
  • fast-element: preserve observable values from before upgrade (#2889) (d84884a)

Features

  • fast-element: add directives for children and slotted references (#2896) (5dc8911)
  • fast-element: add multi property binding support (#2911) (46049ea)
  • design system provider and recipe implementation (#2860) (8c04e15)

0.5.0 (2020-04-02)

Features

  • fast-element: add trusted types for HTML (#2855) (69d44a2)

0.4.0 (2020-03-30)

Bug Fixes

  • attribute bindings in fast components (#2847) (0d25806)
  • fast-element: ensure host attributes have a target name (#2846) (4bd99c9)

Features

0.3.1 (2020-03-25)

Bug Fixes

  • fast-element: add docs and ensure boolean attrs true when empty (#2833) (4bf2c41)

0.3.0 (2020-03-25)

Bug Fixes

  • fast-element: type fixes, api docs, and one op order correction (#2810) (0548e89)
  • view: ensure first/last child correct after removing view (#2819) (7d82ddc)

Features

  • fast-element: boolean attributes and type conversion (#2829) (03f64cd)

Performance Improvements

  • fast-element: optimize view removal and disposal (#2806) (59cc3be)

0.2.1 (2020-03-18)

Note: Version bump only for package @microsoft/fast-element

0.2.0 (2020-03-13)

Bug Fixes

  • fast-element: undefined/null should remove the html attribute (#2749) (82dbf74)

Features

  • fast-element: attached behaviors (#2784) (170eed7)
  • fast-element: base shadow and element options on defaults (#2782) (73fabda)
  • fast-element: enable host instructions (#2760) (8675585)
  • fast-element: streamline custom event emit (#2777) (b3250ec)
  • export when from the root of fast-element (#2739) (3e290d3)
  • fast-element: simpler element definition without decorators (#2730) (d89e9ca)

Performance Improvements

0.1.0 (2020-02-28)

Bug Fixes

  • fast-element: prevent duplicate subscription and queuing (#2678) (99a24d8)

Features

  • fast-element: add initial source from prototype (#2675) (f8c3226)

Performance Improvements

  • fast-element: improve subscribe/unsubscribe by reducing alloc (#2679) (1957c6f)
  • fast-element: improve synthetic view creation speed (#2680) (2e2b549)
  • fast-element: new strategy for array observation and repeat (#2684) (6f2f272)