> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/frameworks-y-samples.md).

# Frameworks and Samples

This is a quick guide on how to use the SDK Web library in any current framework.

{% hint style="warning" %}
Although SDK Web is compatible with vanilla HTML integrations, it is recommended to avoid this type of implementation, since some configurations may not be possible due to the types that basic HTML does not handle.
{% endhint %}

## TypeScript <a href="#typescript" id="typescript"></a>

All Facephi components are typed to be used in TypeScript environments (whether plain TypeScript or integrated into frameworks).

This configuration will be useful during the library implementation. These types will work in any framework, but their use may differ depending on the environment.

**Usage example**:

This is a simple usage example for a plain TS environment. The types offered by the different components can be used in any framework with TS integration. This will provide fixes and autocomplete functions in the IDE.

```ts
const facephiSdkProvider: HTMLFacephiSdkProviderElement = document.createElement('facephi-sdk-provider');
facephiSdkProvider.apikey = process.env.FACEPHI_SDK_APIKEY;
facephiSdkProvider.addEventListener('emitData', handleEmitData);
```

***

## SDK Web Integration in frameworks <a href="#integraciones-de-frameworks" id="integraciones-de-frameworks"></a>

The SDK Web library based on Web Components can be integrated into any framework with the configuration required by each environment.

It is necessary to use the `defineCustomElements` that the library offers to initialize the components.

```js
import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader';
defineFacephiSdkCustomComponent(window);
```

Type hints in an IDE might not be displayed in some HTML sections in frameworks. To take advantage of these features, it is recommended to implement the configuration of the various components in the code section or install the required extensions.

The following examples are generalized approaches, since each environment may have different configurations or versions. Once the components are defined, integration is practically the same in all cases.

### Angular <a href="#angular" id="angular"></a>

In Angular implementations, you must add the `CUSTOM_ELEMENTS_SCHEMA` to recognize components as custom elements.

```js
// App-component.ts
@Component({
    selector: 'AppComponent',
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    templateUrl: './App-component.html',
    // ...
})
export class AppComponent {
  //...
}
```

> There is a library `@facephi/sdk-web-angular` for native Angular integrations. See the section [SDK Web Angular](#sdk-web-angular) for more information.

### React / Next <a href="#react--next" id="react--next"></a>

In React / Next implementations, to recognize the custom component of the widget as a native HTML element, it needs to be registered as an intrinsic element. All its properties, events, and methods could be defined in the same way.

```js
// facephi-wdk-provider.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'facephi-sdk-provider': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLFacephiSDKProviderElement>,
      HTMLFacephiSDKProviderElement
    >;
  }
}
```

> There is a library `@facephi/sdk-web-react` for native React integrations. See the section [SDK Web React](#sdk-web-react) for more information.

### Vue / Nuxt <a href="#vue--nuxt" id="vue--nuxt"></a>

In Vue / Nuxt implementations, the provider custom component must be defined as a native HTML element as in the following example.

```js
// vue.config.js
module.exports = {
  (...)
  chainWebpack: (config) => {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('facephi-sdk-provider'),
    },
  };
},
```

### Server-side rendering applications <a href="#renderizado-del-lado-del-servidor" id="renderizado-del-lado-del-servidor"></a>

In server-side rendering (SSR) implementations, components must be loaded on the client side to avoid malfunction.

***

## Framework-Specific Wrappers <a href="#wrappers-espec-c3-adficos-de-framework" id="wrappers-espec-c3-adficos-de-framework"></a>

Although the Web Components SDK library (`@facephi/sdk-web-wc`) can be used in any modern framework, there are framework-specific wrappers available for React and Angular to provide a more native development experience.

In these libraries, all the components are already defined and ready to be implemented. These packages use the vanilla library internally, so the same exports (enums, types, and methods) are available from them.

### SDK Web React <a href="#sdk-web-react" id="sdk-web-react"></a>

The SDK Web React library (`@facephi/sdk-web-react`) provides React-specific wrappers that allow you to use Facephi components as native React components with full TypeScript support.

**Installation:**

```bash
npm install @facephi/sdk-web-react
```

**IDE Tip**

Optional: Add a library import in the main file so the IDE knows where to find the exports.

```js
import "@facephi/sdk-web-react";
import "@facephi/sdk-web-wc";
```

**Usage example:**

```tsx
import React from 'react';
import { SDKProvider, SelphidWidget } from '@facephi/sdk-web-react';

function App() {
  return (
    <SDKProvider apikey={process.env.FACEPHI_SDK_APIKEY}>
      <SelphidWidget />
    </SDKProvider>
  );
}

export default App;
```

**Features:**

* Native React components with full lifecycle support
* TypeScript definitions for all components and props
* React-friendly event handling

### SDK Web Angular <a href="#sdk-web-angular" id="sdk-web-angular"></a>

The SDK Web Angular library (`@facephi/sdk-web-angular`) offers Angular-specific wrappers that work seamlessly with Angular's component system and the Angular Language Service.

:::note This library is offered for Angular 19 or later integrations. The Facephi team cannot guarantee correct performance in earlier versions. :::

**Installation:**

```bash
npm install @facephi/sdk-web-angular
```

**IDE Tip**

Optional: Add a library import in the main file so the IDE knows where to find the exports.

```js
import "@facephi/sdk-web-angular";
import "@facephi/sdk-web-wc";
```

**Usage example:**

```typescript
import { Component } from '@angular/core';
import { SDKProviderComponent, SelphidWidgetComponent } from '@facephi/sdk-web-angular';

@Component({
  selector: 'app-root',
  template: `
    <facephi-sdk-provider [apikey]="apiKey">
      <facephi-selphid-widget></facephi-selphid-widget>
    </facephi-sdk-provider>
  `,
  standalone: true,
  imports: [SDKProviderComponent, SelphidWidgetComponent]
})
export class AppComponent {
  apiKey = process.env.FACEPHI_SDK_APIKEY;
}
```

**Features:**

* Native Angular components
* Full IntelliSense and autocomplete support through Angular Language Service
* Full TypeScript integration
* Compatible with standalone components and NgModules

The SDK Web can be implemented in most current frameworks.

There are two versions of the SDK Web library:

* **SDK Web WebComponents**: web-components library, compatible with most frameworks and environments.

  ```jsx
  <facephi-sdk-provider>
      <facephi-selphid-widget />
  </facephi-sdk-provider>
  ```
* **SDK Web React**: React component version. This library has all the functionality of the WebComponents version, but with the syntax applicable to React.

  ```jsx
  <FacephiSdkProvider>
      <FacephiSelphidWidget />
  </FacephiSdkProvider>
  ```

***

## Programming examples

The Facephi team offers a repository with a wide range of examples and purposes for integrating the products offered by Facephi.

Web SDK programming examples repository: <https://github.com/facephi/sdk-web-examples>.