> 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 because of 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 autocompletion features 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 provides 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 shown 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 approximations, since each environment may have different configurations or versions. Once the components are defined, the integration is practically the same in all cases.

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

In Angular implementations, the `CUSTOM_ELEMENTS_SCHEMA` must be added to recognize the 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 widget's custom component 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
    >;
  }
}
```

> A library is available `@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's 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, the 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 SDK Web Components 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 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 perfectly with Angular's component system and the Angular Language Service.

:::note This library is offered for Angular 19 or higher 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 autocompletion support through Angular Language Service
* Full TypeScript integration
* Compatible with standalone components and NgModules

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 components version. This library includes all the functionality of the WebComponents version, but with syntax applicable to React.

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

***

## Code examples

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

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