feat(runtime): allow class extending by johnjenkins · Pull Request #6362 · stenciljs/core

johnjenkins · 2025-07-31T16:43:35Z

What is the current behavior?

Stencil component classes currently do not allow extends ... mainly because it utilises static-analysis to gather meta for properties, methods, events and docs - this is hard for dynamically extending classes.

GitHub Issue Number:

What is the new behavior?

closes Feature Request : @Props OR component inheritance #2844
closes Add props at compile time #2559

This is a decent size PR to enable all kinds of extends within Stencil:

Components can extend from other components
Components can extend from abstract, Stencil decorated classes that are not designed to be full components
Components can extend from 3rd party / node_module stencil components (via dist/collection)
Components can extend from non-stencil classes
The extend tree / chain is preserved and works appropriately

The only caveat is that Stencil decorated classes can only be extended from if the tsconfig target is es2022 or higher. This is due to how Stencil initialises classes by changing their prototype, how older classes instantiate class properties within the constructor and the order of super() initialisation.

Documentation

Does this introduce a breaking change?

Yes
No

Testing

lots of new spec tets
lots of new wdio tests

Other information

src/compiler/transformers/transform-utils.ts

danielleroux · 2025-08-05T11:03:26Z

@johnjenkins any plans also to support mixins pattern?

johnjenkins · 2025-08-05T11:06:44Z

@danielleroux can you give an example? 🙂

danielleroux · 2025-08-06T05:04:10Z

@danielleroux can you give an example? 🙂

import { Component, h, Host, Prop, State } from '@stencil/core';

type StencilElement = HTMLElement & ....;
type Constructor<T> = new (...args: any[]) => T;

declare class ValidationInterface {
  isValid: boolean;
  errorMessage: string;
  handleValidation(value: string): void;
  renderValidationFeedback(): unknown;
}

declare class LoadingInterface {
  isLoading: boolean;
  setLoading(loading: boolean): void;
  renderLoading(container: unknown): unknown;
}

const Validation = <T extends Constructor<StencilElement>>(superClass: T) => {
  class ValidationElement extends superClass {
    @Prop({ mutable: true }) isValid: boolean = true;
    @Prop({ mutable: true }) errorMessage: string = '';

    handleValidation(value: string): void {
      if (value.trim() === '') {
        this.isValid = false;
        this.errorMessage = 'This field cannot be empty.';
      } else {
        this.isValid = true;
        this.errorMessage = '';
      }
    }

    renderValidationFeedback(): unknown {
      if (!this.isValid && this.errorMessage) {
        return <div class="error-message">{this.errorMessage}</div>;
      }
      return null;
    }
  }
  return ValidationElement as Constructor<ValidationInterface> & T;
};

const Loading = <T extends Constructor<StencilElement>>(superClass: T) => {
  class LoadingElement extends superClass {
    @State() isLoading: boolean = false;

    setLoading(loading: boolean) {
      this.isLoading = loading;
    }

    renderLoading(container: unknown): unknown {
      if (this.isLoading) {
        return <div class="loading-spinner">Loading...</div>;
      }
      return container;
    }
  }
  return LoadingElement as Constructor<LoadingInterface> & T;
};

@Component({
  tag: 'example-component',
  styleUrl: 'example.css',
  shadow: true,
})
export class ExampleComponent extends Loading(Validation(HTMLElement)) {
  onValueChange(event: Event) {
    const input = event.target as HTMLInputElement;
    this.setLoading(true);
    this.handleValidation(input.value);
    this.setLoading(false);
  }

  render() {
    return (
      <Host>
        {this.renderLoading(
          <input
            type="text"
            placeholder="Type something..."
            onChange={this.onValueChange.bind(this)}
          />
        )}
        {this.renderValidationFeedback()}
      </Host>
    );
  }
}

@Component({
  tag: 'example-component',
  styleUrl: 'example.css',
  shadow: true,
})
export class MyComponent extends Loading(HTMLElement) {

  componentDidLoad() {
     setLoading(true);
     setTimeout(() => {
         {this.renderValidationFeedback()}
     }, 1000);
  }

  render() {
    return (
      <Host>
        {this.renderLoading(
          <input
            type="text"
            placeholder="Type something..."
            onChange={this.onValueChange.bind(this)}
          />
        )}
      </Host>
    );
  }
}

Source: https://lit.dev/docs/composition/mixins/

johnjenkins · 2025-08-06T07:47:59Z

@danielleroux can you give an example? 🙂

import { Component, h, Host, Prop, State } from '@stencil/core';

type StencilElement = HTMLElement & ....;
type Constructor<T> = new (...args: any[]) => T;

declare class ValidationInterface {
  isValid: boolean;
  errorMessage: string;
  handleValidation(value: string): void;
  renderValidationFeedback(): unknown;
}

declare class LoadingInterface {
  isLoading: boolean;
  setLoading(loading: boolean): void;
  renderLoading(container: unknown): unknown;
}

const Validation = <T extends Constructor<StencilElement>>(superClass: T) => {
  class ValidationElement extends superClass {
    @Prop({ mutable: true }) isValid: boolean = true;
    @Prop({ mutable: true }) errorMessage: string = '';

    handleValidation(value: string): void {
      if (value.trim() === '') {
        this.isValid = false;
        this.errorMessage = 'This field cannot be empty.';
      } else {
        this.isValid = true;
        this.errorMessage = '';
      }
    }

    renderValidationFeedback(): unknown {
      if (!this.isValid && this.errorMessage) {
        return <div class="error-message">{this.errorMessage}</div>;
      }
      return null;
    }
  }
  return ValidationElement as Constructor<ValidationInterface> & T;
};

const Loading = <T extends Constructor<StencilElement>>(superClass: T) => {
  class LoadingElement extends superClass {
    @State() isLoading: boolean = false;

    setLoading(loading: boolean) {
      this.isLoading = loading;
    }

    renderLoading(container: unknown): unknown {
      if (this.isLoading) {
        return <div class="loading-spinner">Loading...</div>;
      }
      return container;
    }
  }
  return LoadingElement as Constructor<LoadingInterface> & T;
};

@Component({
  tag: 'example-component',
  styleUrl: 'example.css',
  shadow: true,
})
export class ExampleComponent extends Loading(Validation(HTMLElement)) {
  onValueChange(event: Event) {
    const input = event.target as HTMLInputElement;
    this.setLoading(true);
    this.handleValidation(input.value);
    this.setLoading(false);
  }

  render() {
    return (
      <Host>
        {this.renderLoading(
          <input
            type="text"
            placeholder="Type something..."
            onChange={this.onValueChange.bind(this)}
          />
        )}
        {this.renderValidationFeedback()}
      </Host>
    );
  }
}

@Component({
  tag: 'example-component',
  styleUrl: 'example.css',
  shadow: true,
})
export class MyComponent extends Loading(HTMLElement) {

  componentDidLoad() {
     setLoading(true);
     setTimeout(() => {
         {this.renderValidationFeedback()}
     }, 1000);
  }

  render() {
    return (
      <Host>
        {this.renderLoading(
          <input
            type="text"
            placeholder="Type something..."
            onChange={this.onValueChange.bind(this)}
          />
        )}
      </Host>
    );
  }
}

Source: https://lit.dev/docs/composition/mixins/

I see - thanks!
I can’t imagine this kind of pattern would be easy to get working.
The nature of static analysis means we need reliable, repeatable rules we can pick apart to get what we need. The nature of something like

const Loading = <T extends Constructor<StencilElement>>(superClass: T) => { class LoadingElement extends superClass

is just too dynamic to pick apart in a reliable way.

if we can standardise around an api to do essentially do this for devs (eg an `@Mixin(class1, class2)’ then it would be fine

src/compiler/bundle/typescript-plugin.ts

src/compiler/transformers/component-lazy/transform-lazy-component.ts

src/compiler/transformers/component-native/tranform-to-native-component.ts

src/compiler/transformers/create-event.ts

src/compiler/transformers/static-to-meta/component.ts

sitaramyadav

Added few comments

…at-extend-class

feat(runtime): allow class extending

10a1102

johnjenkins requested a review from a team as a code owner July 31, 2025 16:43

chore: fix tests

062301c

jttommy reviewed Aug 4, 2025

View reviewed changes

src/compiler/transformers/transform-utils.ts Outdated Show resolved Hide resolved

John Jenkins and others added 3 commits August 4, 2025 23:42

feat: extend Stencil decorated classes!

de9c45d

chore: assign / reuse foundSuper

4f7e3be

Merge branch 'main' into feat-extend-class

29a53ec

johnjenkins marked this pull request as draft August 4, 2025 23:09

John Jenkins added 3 commits August 5, 2025 00:33

chore: fix test

b90abc2

chore: format

678ae84

chore: fix test

ab914e4

chore: read all the extended tree class methods

2d8bab7

John Jenkins added 2 commits August 7, 2025 01:14

chore: added some unit tests

be7d1e3

chore: more unit tests

2ecafeb