Home

A thin, full-stack, web framework.

Ease of use

Write the same markup, styling and scripting languages for both server and client side.
The ones that you already know and use everywhere else: HTML, CSS and JavaScript.

Standards oriented

Built with a platform-minded philosophy. Every time a standard can be leveraged for a task, it should be.
It also means fewer vendor-specific idioms to churn on and a more portable codebase overall.
Stop re-implementing the wheel, and embrace future-proof APIs, you’ll thank yourself later!

Developer Experience

The DX bar has been constantly raised, alongside developers’ expectations about their everyday tooling.
The “Vanilla” community is full of gems, in a scattered way.
Gracile provides an integrated, out-of-the-box experience while keeping non-core opinions as opt-ins.

Convention over configuration

Finding the right balance between convenience and freedom is tricky.
Hopefully, more and more patterns will be established in the full-stack JS space.

Gracile is inspired by those widespread practices that will make you feel at home.

Performances

Speed is not the main goal for Gracile, that’s because it is just the sane default you’ll start with.
Avoiding complex template transformations, or surgically shipping client-side JS are just a few facets of what makes Gracile a “do more with less” power tool.

Annotated example

Tip

You can hover/tap source code tokens, like in your local editor, to get more insights.


📄 /src/document.ts

import { htmlfunction html(strings: TemplateStringsArray, ...values: unknown[]): ServerRenderedTemplateA lit-html template that can only be rendered on the server, and cannot be
hydrated.
These templates can be used for rendering full documents, including the
doctype, and rendering into elements that Lit normally cannot, like
<title>, <textarea>, <template>, and non-executing <script> tags
like <script type="text/json">. They are also slightly more efficient than
normal Lit templates, because the generated HTML doesn't need to include
markers for updating.
Server-only html templates can be composed, and combined, and they support
almost all features that normal Lit templates do, with the exception of
features that don't have a pure HTML representation, like event handlers or
property bindings.
Server-only html templates can only be rendered on the server, they will
throw an Error if created in the browser. However if you render a normal Lit
template inside a server-only template, then it can be hydrated and updated.
Likewise, if you place a custom element inside a server-only template, it can
be hydrated and update like normal.
A server-only template can't be rendered inside a normal Lit template. } from '@gracile/gracile/server-html';
import { helpersconst helpers: {
    fullHydration: import("@lit-labs/ssr").ServerRenderedTemplate;
    polyfills: {
        declarativeShadowDom: import("@lit-labs/ssr").ServerRenderedTemplate;
        requestIdleCallback: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
    pageAssets: import("@lit-labs/ssr").ServerRenderedTemplate;
    dev: {
        errors: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
} } from '@gracile/gracile/document';

export const documentconst document: (options: {
    url: URL;
    title?: string;
}) => ServerRenderedTemplate = (optionsoptions: {
    url: URL;
    title?: string;
}: { urlurl: URL: URL; titletitle?: string | undefined?: string }) => htmlfunction html(strings: TemplateStringsArray, ...values: unknown[]): ServerRenderedTemplateA lit-html template that can only be rendered on the server, and cannot be
hydrated.
These templates can be used for rendering full documents, including the
doctype, and rendering into elements that Lit normally cannot, like
<title>, <textarea>, <template>, and non-executing <script> tags
like <script type="text/json">. They are also slightly more efficient than
normal Lit templates, because the generated HTML doesn't need to include
markers for updating.
Server-only html templates can be composed, and combined, and they support
almost all features that normal Lit templates do, with the exception of
features that don't have a pure HTML representation, like event handlers or
property bindings.
Server-only html templates can only be rendered on the server, they will
throw an Error if created in the browser. However if you render a normal Lit
template inside a server-only template, then it can be hydrated and updated.
Likewise, if you place a custom element inside a server-only template, it can
be hydrated and update like normal.
A server-only template can't be rendered inside a normal Lit template.`
  <!doctype html>
  <html
    lang="en"
    class=${`page${optionsoptions: {
    url: URL;
    title?: string;
}.urlurl: URL.pathnameURL.pathname: stringMDN Reference.replaceString.replace(searchValue: string | RegExp, replaceValue: string): string (+3 overloads)Replaces text in a string, using a regular expression or search string.
@paramsearchValue A string or regular expression to search for.@paramreplaceValue A string containing the text to replace. When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` flag is set (or only those matches at the beginning, if the `y` flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.('/', '-') || 'home'}`}
  >
    <head>
       Helpers 
      ${helpersconst helpers: {
    fullHydration: import("@lit-labs/ssr").ServerRenderedTemplate;
    polyfills: {
        declarativeShadowDom: import("@lit-labs/ssr").ServerRenderedTemplate;
        requestIdleCallback: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
    pageAssets: import("@lit-labs/ssr").ServerRenderedTemplate;
    dev: {
        errors: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
}.fullHydrationfullHydration: ServerRenderedTemplate}

       Global assets 
      <link rel="stylesheet" href="/src/styles/global.scss" />
      <script type="module" src="/src/document.client.ts"></script>

       Route specific sibling assets 
      ${helpersconst helpers: {
    fullHydration: import("@lit-labs/ssr").ServerRenderedTemplate;
    polyfills: {
        declarativeShadowDom: import("@lit-labs/ssr").ServerRenderedTemplate;
        requestIdleCallback: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
    pageAssets: import("@lit-labs/ssr").ServerRenderedTemplate;
    dev: {
        errors: import("@lit-labs/ssr").ServerRenderedTemplate;
    };
}.pageAssetspageAssets: ServerRenderedTemplate}

       SEO 
      <title>${optionsoptions: {
    url: URL;
    title?: string;
}.titletitle?: string | undefined ?? 'My Website'}</title>

      <!-- ... -->
    </head>

    <body>
       Current route's page injection 
      <route-template-outlet></route-template-outlet>
    </body>
  </html>
`;

📄 /src/routes/index.ts

import { htmlconst html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>Interprets a template literal as an HTML template that can efficiently
render to and update a container.
const header = (title: string) => html`<h1>${title}</h1>`;

The html tag returns a description of the DOM to render as a value. It is
lazy, meaning no work is done until the template is rendered. When rendering,
if a template comes from the same expression as a previously rendered result,
it's efficiently updated instead of replaced. } from 'lit';
import { defineRoutefunction defineRoute<GetHandlerData extends R.HandlerDataHtml = undefined, PostHandlerData extends R.HandlerDataHtml = undefined, StaticPathOptions extends R.StaticPathOptionsGeneric | undefined = undefined, RouteContext extends R.RouteContextGeneric = {
    url: URL;
    props: StaticPathOptions extends {
        params: any;
        props: any;
    } ? StaticPathOptions["props"] : GetHandlerData | PostHandlerData extends undefined ? never : {
        GET: GetHandlerData extends Response ? never : GetHandlerData;
        POST: PostHandlerData extends Response ? never : PostHandlerData;
    };
    params: StaticPathOptions extends {
        params: any;
    } ? StaticPathOptions["params"] : R.Params;
}>(options: {
    handler?: StaticPathOptions extends object ? never : R.Handler<Response> | {
        GET?: R.Handler<GetHandlerData>;
        POST?: R.Handler<PostHandlerData>;
        QUERY?: R.Handler;
        PUT?: R.Handler;
        PATCH?: R.Handler;
        DELETE?: R.Handler;
        HEAD?: R.Handler;
        OPTIONS?: R.Handler;
    };
    staticPaths?: (() => StaticPathOptions[]) | undefined;
    document?: R.DocumentTemplate<RouteContext>;
    template?: R.BodyTemplate<RouteContext>;
}): (RouteModule: typeof R.RouteModule) => R.RouteModuleDefines a route.
See in the documentation. } from '@gracile/gracile/route';

import { dbconst db: {
    query<T>(str: string): T[];
}Dummy DB handler…, sqlfunction sql(str: string): stringDummy SQL template literal…, Achievementtype Achievement = {
    name: string;
    date: Date;
} } from '../lib/db.js';

import { documentconst document: (options: {
    url: URL;
    title?: string;
}) => ServerRenderedTemplate } from '../document.js';

import * as homeReadmemodule "*.md" from '../content/README.md' with { type: 'markdown-lit' };

import type { MyElementclass MyElement } from '../features/my-element.ts';
import '../features/my-element.js';

export default defineRoutedefineRoute<undefined, Response | {
    success: boolean;
    message: "Wrong input!";
}, undefined, {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}>(options: {
    ...;
}): (RouteModule: typeof RouteModule) => RouteModuleDefines a route.
See in the documentation.({
  handlerhandler?: Handler<Response> | {
    GET?: Handler<undefined> | undefined;
    POST?: Handler<Response | {
        success: boolean;
        message: "Wrong input!";
    }> | undefined;
    ... 5 more ...;
    OPTIONS?: Handler<...> | undefined;
} | undefined: {
    POSTPOST?: Handler<Response | {
    success: boolean;
    message: "Wrong input!";
}> | undefined: async (contextcontext: {
    url: URL;
    params: Params;
    request: Request;
    response: ResponseInit;
}) => {
      const formDataconst formData: FormData = await contextcontext: {
    url: URL;
    params: Params;
    request: Request;
    response: ResponseInit;
}.requestrequest: Request.formDataBody.formData(): Promise<FormData>MDN Reference();
      const nameconst name: string | undefined = formDataconst formData: FormData.getFormData.get(name: string): FormDataEntryValue | nullMDN Reference('achievement')?.toStringfunction toString(): stringReturns a string representation of a string.();

      if (nameconst name: string | undefined) {
        await dbconst db: {
    query<T>(str: string): T[];
}Dummy DB handler….queryquery<unknown>(str: string): unknown[](sqlfunction sql(str: string): stringDummy SQL template literal…`INSERT INTO achievements (name); VALUES (${nameconst name: string})`);

        return Responsevar Response: {
    new (body?: BodyInit | null, init?: ResponseInit): Response;
    prototype: Response;
    error(): Response;
    json(data: any, init?: ResponseInit): Response;
    redirect(url: string | URL, status?: number): Response;
}This Fetch API interface represents the response to a request.
MDN Reference.redirectfunction redirect(url: string | URL, status?: number): ResponseMDN Reference(contextcontext: {
    url: URL;
    params: Params;
    request: Request;
    response: ResponseInit;
}.urlurl: URL, 303);
      }

      const messageconst message: "Wrong input!" = 'Wrong input!' as consttype const = "Wrong input!";
      contextcontext: {
    url: URL;
    params: Params;
    request: Request;
    response: ResponseInit;
}.responseresponse: ResponseInitLet you mutate the downstream page response.
It doesn't take effect if you're returning the
response yourself before (within your request handler)..statusResponseInit.status?: number | undefined = 400;
      contextcontext: {
    url: URL;
    params: Params;
    request: Request;
    response: ResponseInit;
}.responseresponse: ResponseInitLet you mutate the downstream page response.
It doesn't take effect if you're returning the
response yourself before (within your request handler)..statusTextResponseInit.statusText?: string | undefined = messageconst message: "Wrong input!";
      return { successsuccess: boolean: false, messagemessage: "Wrong input!" };
    },
  },

  documentdocument?: DocumentTemplate<{
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}> | undefined: (contextcontext: {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}) =>
    documentfunction document(options: {
    url: URL;
    title?: string;
}): ServerRenderedTemplate({ urlurl: URL: contextcontext: {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}.urlurl: URL, titletitle?: string | undefined: homeReadmemodule "*.md".title }),

  templatetemplate?: BodyTemplate<{
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}> | undefined: async (contextcontext: {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}) => {
    const initialDataconst initialData: {
    foo: string;
} = { foofoo?: string | undefined: 'bar' } satisfies MyElementclass MyElement['initialData'];

    const achievementsconst achievements: Achievement[] = await dbconst db: {
    query<T>(str: string): T[];
}Dummy DB handler….queryquery<Achievement>(str: string): Achievement[]<Achievementtype Achievement = {
    name: string;
    date: Date;
}>(
      sqlfunction sql(str: string): stringDummy SQL template literal…`SELECT * FROM achievements`,
    );

    return htmlconst html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>Interprets a template literal as an HTML template that can efficiently
render to and update a container.
const header = (title: string) => html`<h1>${title}</h1>`;

The html tag returns a description of the DOM to render as a value. It is
lazy, meaning no work is done until the template is rendered. When rendering,
if a template comes from the same expression as a previously rendered result,
it's efficiently updated instead of replaced.`
       You can use inline (deferred) modules or in-path scripts… 
      <script type="module">
        await new Promise((r) => setTimeout(() => r(console.log('Hi!')), 1500));
      </script>

      <h1>${homeReadmemodule "*.md".title}</h1>

      <main>
        <article>${homeReadmemodule "*.md".content}</article>
      </main>

      <aside>
        <form method="post">
          <input type="text" name="achievement" />
          <button>Add achievement</button>

          <span>${contextcontext: {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}.propsprops: {
    GET: undefined;
    POST: {
        success: boolean;
        message: "Wrong input!";
    };
}.POSTtype POST: {
    success: boolean;
    message: "Wrong input!";
}?.messagemessage: "Wrong input!"}</span>
        </form>

        <my-element initialData=${JSONvar JSON: JSONAn intrinsic object that provides functions to convert JavaScript values to and from the JavaScript Object Notation (JSON) format..stringifyJSON.stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string (+1 overload)Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
@paramvalue A JavaScript value, usually an object or array, to be converted.@paramreplacer A function that transforms the results.@paramspace Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.(initialDataconst initialData: {
    foo: string;
})}></my-element>
        <my-client-only-element></my-client-only-element>

        <footer>
          ${achievementsconst achievements: Achievement[].mapArray<Achievement>.map<TemplateResult<1>>(callbackfn: (value: Achievement, index: number, array: Achievement[]) => TemplateResult<1>, thisArg?: any): TemplateResult<...>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.(
            (achievementachievement: Achievement) =>
              htmlconst html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>Interprets a template literal as an HTML template that can efficiently
render to and update a container.
const header = (title: string) => html`<h1>${title}</h1>`;

The html tag returns a description of the DOM to render as a value. It is
lazy, meaning no work is done until the template is rendered. When rendering,
if a template comes from the same expression as a previously rendered result,
it's efficiently updated instead of replaced.`<section class=${`achievement-${achievementachievement: Achievement.namename: string}`}>
                <h1>${achievementachievement: Achievement.namename: string}</h1>
                <p>${achievementachievement: Achievement.datedate: Date}</p>
              </section>`,
          )}
        </footer>
      </aside>

      <footer>
        <small>You are visiting ${contextcontext: {
    url: URL;
    props: {
        GET: undefined;
        POST: {
            success: boolean;
            message: "Wrong input!";
        };
    };
    params: Params;
}.urlurl: URL.hrefURL.href: stringMDN Reference}</small>
      </footer>
    `;
  },
});

📄 /src/routes/index.client.ts

 Importing your components in this page's client bundle entrypoint will make the server markup alive.

requestIdleCallbackfunction requestIdleCallback(callback: IdleRequestCallback, options?: IdleRequestOptions): numberMDN Reference(() => import('../features/my-element.js'));
// ...

 Don't import on server-side, if you want a client-only element.
import '../features/my-client-only-element.js';

consolevar console: ConsoleThe console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without calling require('console').

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr

Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see[source](https://github.com/nodejs/node/blob/v20.11.1/lib/console.js).logConsole.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout

See util.format() for more information.
@sincev0.1.100('Welcome', navigatorvar navigator: NavigatorMDN Reference.userAgentNavigatorID.userAgent: stringMDN Reference);
// ...

📄 /src/features/my-element.ts

import { LitElementclass LitElementBase element class that manages element properties and attributes, and
renders a lit-html template.
To define a component, subclass LitElement and implement a
render method to provide the component's template. Define properties
using the
{@linkcode
LitElement.properties
properties
}
property or the
{@linkcode
property
}
decorator., cssconst css: (strings: TemplateStringsArray, ...values: (CSSResultGroup | number)[]) => CSSResultA template literal tag which can be used with LitElement's
{@linkcode
LitElement.styles
}
property to set element styles.
For security reasons, only literal string values and number may be used in
embedded expressions. To incorporate non-literal values
{@linkcode
unsafeCSS
}
may be used inside an expression., htmlconst html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>Interprets a template literal as an HTML template that can efficiently
render to and update a container.
const header = (title: string) => html`<h1>${title}</h1>`;

The html tag returns a description of the DOM to render as a value. It is
lazy, meaning no work is done until the template is rendered. When rendering,
if a template comes from the same expression as a previously rendered result,
it's efficiently updated instead of replaced. } from 'lit';
import { customElementconst customElement: (tagName: string) => CustomElementDecoratorClass decorator factory that defines the decorated class as a custom element.
@customElement('my-element')
class MyElement extends LitElement {
render() {
return html``;
}
}
```@categoryDecorator@paramtagName The tag name of the custom element to define., propertyfunction property(options?: PropertyDeclaration): PropertyDecoratorA class field or accessor decorator which creates a reactive property that
reflects a corresponding attribute value. When a decorated property is set
the element will update and render. A
{@linkcode
PropertyDeclaration
}
may
optionally be supplied to configure property features.
This decorator should only be used for public fields. As public fields,
properties should be considered as primarily settable by element users,
either via attribute or the property itself.
Generally, properties that are changed by the element should be private or
protected fields and should use the
{@linkcode
state
}
decorator.
However, sometimes element code does need to set a public property. This
should typically only be done in response to user interaction, and an event
should be fired informing the user; for example, a checkbox sets its
checked property when clicked and fires a changed event. Mutating public
properties should typically not be done for non-primitive (object or array)
properties. In other cases when an element needs to manage state, a private
property decorated via the
{@linkcode
state
}
decorator should be used. When
needed, state properties can be initialized via public properties to
facilitate complex interactions.
class MyElement {
@property({ type: Boolean })
clicked = false;
}
```@categoryDecorator@ExportDecoratedItems } from 'lit/decorators.js';
import { styleMapconst styleMap: (styleInfo: Readonly<StyleInfo>) => import("../directive.js").DirectiveResult<typeof StyleMapDirective>A directive that applies CSS properties to an element.
styleMap can only be used in the style attribute and must be the only
expression in the attribute. It takes the property names in the
{@link
StyleInfo
styleInfo
}
object and adds the properties to the inline
style of the element.
Property names with dashes (-) are assumed to be valid CSS
property names and set on the element's style object using setProperty().
Names without dashes are assumed to be camelCased JavaScript property names
and set on the element's style object using property assignment, allowing the
style object to translate JavaScript-style names to CSS property names.
For example styleMap({backgroundColor: 'red', 'border-top': '5px', '--size': '0'}) sets the background-color, border-top and --size properties.
@paramstyleInfo@see{@link https://lit.dev/docs/templates/directives/#stylemap styleMap code samples on Lit.dev} } from 'lit/directives/style-map.js';

@customElementfunction customElement(tagName: string): CustomElementDecoratorClass decorator factory that defines the decorated class as a custom element.
@customElement('my-element')
class MyElement extends LitElement {
render() {
return html``;
}
}
```@categoryDecorator@paramtagName The tag name of the custom element to define.('my-element')
export class MyElementclass MyElement extends LitElementclass LitElementBase element class that manages element properties and attributes, and
renders a lit-html template.
To define a component, subclass LitElement and implement a
render method to provide the component's template. Define properties
using the
{@linkcode
LitElement.properties
properties
}
property or the
{@linkcode
property
}
decorator. {
  static readonly GREETINGMyElement.GREETING: "Hello" = 'Hello';

  @propertyfunction property(options?: PropertyDeclaration<unknown, unknown> | undefined): PropertyDecoratorA class field or accessor decorator which creates a reactive property that
reflects a corresponding attribute value. When a decorated property is set
the element will update and render. A
{@linkcode
PropertyDeclaration
}
may
optionally be supplied to configure property features.
This decorator should only be used for public fields. As public fields,
properties should be considered as primarily settable by element users,
either via attribute or the property itself.
Generally, properties that are changed by the element should be private or
protected fields and should use the
{@linkcode
state
}
decorator.
However, sometimes element code does need to set a public property. This
should typically only be done in response to user interaction, and an event
should be fired informing the user; for example, a checkbox sets its
checked property when clicked and fires a changed event. Mutating public
properties should typically not be done for non-primitive (object or array)
properties. In other cases when an element needs to manage state, a private
property decorated via the
{@linkcode
state
}
decorator should be used. When
needed, state properties can be initialized via public properties to
facilitate complex interactions.
class MyElement {
@property({ type: Boolean })
clicked = false;
}
```@categoryDecorator@ExportDecoratedItems({ typePropertyDeclaration<unknown, unknown>.type?: unknownIndicates the type of the property. This is used only as a hint for the
converter to determine how to convert the attribute
to/from a property.: Objectvar Object: ObjectConstructorProvides functionality common to all JavaScript objects. }) initialDataMyElement.initialData: {
    foo?: string;
}: { foofoo?: string | undefined?: string } = {};

  @propertyfunction property(options?: PropertyDeclaration<unknown, unknown> | undefined): PropertyDecoratorA class field or accessor decorator which creates a reactive property that
reflects a corresponding attribute value. When a decorated property is set
the element will update and render. A
{@linkcode
PropertyDeclaration
}
may
optionally be supplied to configure property features.
This decorator should only be used for public fields. As public fields,
properties should be considered as primarily settable by element users,
either via attribute or the property itself.
Generally, properties that are changed by the element should be private or
protected fields and should use the
{@linkcode
state
}
decorator.
However, sometimes element code does need to set a public property. This
should typically only be done in response to user interaction, and an event
should be fired informing the user; for example, a checkbox sets its
checked property when clicked and fires a changed event. Mutating public
properties should typically not be done for non-primitive (object or array)
properties. In other cases when an element needs to manage state, a private
property decorated via the
{@linkcode
state
}
decorator should be used. When
needed, state properties can be initialized via public properties to
facilitate complex interactions.
class MyElement {
@property({ type: Boolean })
clicked = false;
}
```@categoryDecorator@ExportDecoratedItems({ typePropertyDeclaration<unknown, unknown>.type?: unknownIndicates the type of the property. This is used only as a hint for the
converter to determine how to convert the attribute
to/from a property.: Numbervar Number: NumberConstructorAn object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers. }) bgTintMyElement.bgTint: number = 0.5;

  renderMyElement.render(): TemplateResult<1>Invoked on each update to perform rendering tasks. This method may return
any value renderable by lit-html's ChildPart - typically a
TemplateResult. Setting properties inside this method will not trigger
the element to update.
@categoryrendering() {
    return htmlconst html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>Interprets a template literal as an HTML template that can efficiently
render to and update a container.
const header = (title: string) => html`<h1>${title}</h1>`;

The html tag returns a description of the DOM to render as a value. It is
lazy, meaning no work is done until the template is rendered. When rendering,
if a template comes from the same expression as a previously rendered result,
it's efficiently updated instead of replaced.`
      <div
        @click=${() => (this.bgTintMyElement.bgTint: number = Mathvar Math: MathAn intrinsic object that provides basic mathematics functionality and constants..randomMath.random(): numberReturns a pseudorandom number between 0 and 1.())}
        style=${styleMapfunction styleMap(styleInfo: Readonly<StyleInfo>): DirectiveResult<typeof StyleMapDirective>A directive that applies CSS properties to an element.
styleMap can only be used in the style attribute and must be the only
expression in the attribute. It takes the property names in the
{@link
StyleInfo
styleInfo
}
object and adds the properties to the inline
style of the element.
Property names with dashes (-) are assumed to be valid CSS
property names and set on the element's style object using setProperty().
Names without dashes are assumed to be camelCased JavaScript property names
and set on the element's style object using property assignment, allowing the
style object to translate JavaScript-style names to CSS property names.
For example styleMap({backgroundColor: 'red', 'border-top': '5px', '--size': '0'}) sets the background-color, border-top and --size properties.
@paramstyleInfo@see{@link https://lit.dev/docs/templates/directives/#stylemap styleMap code samples on Lit.dev}({ '--bg-tint': this.bgTintMyElement.bgTint: number })}
      >
        ${this.initialDataMyElement.initialData: {
    foo?: string | undefined;
}.foofoo?: string | undefined} - ${MyElementclass MyElement.GREETINGMyElement.GREETING: "Hello"}
      </div>
    `;
  }

  static stylesMyElement.styles: CSSResult[]Array of styles to apply to the element. The styles should be defined
using the
{@linkcode
css
}
tag function, via constructible stylesheets, or
imported from native CSS module scripts.
Note on Content Security Policy:
Element styles are implemented with <style> tags when the browser doesn't
support adopted StyleSheets. To use such <style> tags with the style-src
CSP directive, the style-src value must either include 'unsafe-inline' or
nonce-<base64-value> with <base64-value> replaced be a server-generated
nonce.
To provide a nonce to use on generated <style> elements, set
window.litNonce to a server-generated nonce in your page's HTML, before
loading application code:
<script>
  // Generated and unique per request:
  window.litNonce = 'a1b2c3d4';
</script>
@nocollapse@categorystyles = [
    cssconst css: (strings: TemplateStringsArray, ...values: (CSSResultGroup | number)[]) => CSSResultA template literal tag which can be used with LitElement's
{@linkcode
LitElement.styles
}
property to set element styles.
For security reasons, only literal string values and number may be used in
embedded expressions. To incorporate non-literal values
{@linkcode
unsafeCSS
}
may be used inside an expression.`
      :host {
        display: block;
        margin: 1rem;
      }

      div {
        background: hsl(calc(var(--bg-tint, 0) * 360), 50%, 50%);
      }
    `,
  ];
}

FAQ

Why?

Is it tied to any vendor?

Do I need a specific server runtime?

How does it compare to XYZ?

Do I need to use Web Components / Shadow DOM?

What is the current state of this project?

Home :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Ease of use :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Standards oriented :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Developer Experience :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Convention over configuration :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Performances :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

Annotated example :host { /* display: contents; */ display: inline-flex; align-items: center; justify-content: center; width: var(--gr-icon-width, 100%); height: var(--gr-icon-height, 100%); } svg { width: 100%; height: 100%; }

FAQ

Home

Ease of use

Standards oriented

Developer Experience

Convention over configuration

Performances

Annotated example