React library
Official React components for embedding Ask Users forms and surveys in your React applications.
TypeScript support
Full type definitions included
Lightweight
No heavy dependencies
SSR compatible
Works with Next.js and SSR
Installation
npm
npm install @askusers/widget-react
yarn
yarn add @askusers/widget-react
pnpm
pnpm add @askusers/widget-react
Quick start
Import the components and styles, then use them in your React application.
import { FormWidget, SurveyWidget } from '@askusers/widget-react';
import '@askusers/widget-react/styles';
function App() {
return (
<div>
{/* Inline form */}
<FormWidget
formId="your-form-id"
apiKey="your-api-key"
/>
{/* Inline survey */}
<SurveyWidget
surveyId="your-survey-id"
apiKey="your-api-key"
/>
</div>
);
}Note: The styles import is required for proper widget styling.
FormWidget
Use the FormWidget component to embed any form created in Ask Users. Perfect for contact forms, feedback forms, waitlists, and more.
import { FormWidget } from '@askusers/widget-react';
import '@askusers/widget-react/styles';
function ContactPage() {
return (
<FormWidget
formId="contact-form-id"
apiKey="your-api-key"
theme="auto"
hideTitle={false}
transparentBackground={true}
onSubmitSuccess={() => {
console.log('Form submitted successfully!');
}}
onSubmitError={(error) => {
console.error('Submission failed:', error);
}}
/>
);
}SurveyWidget
Use the SurveyWidget component to embed surveys with multiple pages, conditional logic, and various question types.
import { SurveyWidget } from '@askusers/widget-react';
import '@askusers/widget-react/styles';
function FeedbackPage() {
return (
<SurveyWidget
surveyId="feedback-survey-id"
apiKey="your-api-key"
theme="light"
hideDescription={true}
transparentBackground={true}
onSubmitSuccess={() => {
console.log('Survey completed!');
}}
/>
);
}Props reference
| Prop | Type | Default | Description |
|---|---|---|---|
formId / surveyId * | string | - | The ID of the form or survey to display |
apiKey * | string | - | Your API key (required for form/survey submissions) |
baseUrl | string | api.askusers.org | API base URL (only needed for self-hosted instances) |
theme | 'light' | 'dark' | 'auto' | 'auto' | Color theme. 'auto' detects system preference |
hideTitle | boolean | false | Hide the form/survey title |
hideDescription | boolean | false | Hide the form/survey description |
transparentBackground | boolean | false | Render with transparent background for seamless embedding |
showPoweredBy | boolean | true | Show 'Powered by Ask Users' branding |
className | string | - | Additional CSS classes for the container |
* Required
Callbacks
| Callback | Signature | Description |
|---|---|---|
onLoad | () => void | Called when the form/survey data is loaded |
onSubmit | (data) => void | Called when the user submits with form data |
onSubmitSuccess | () => void | Called after successful submission |
onSubmitError | (error: Error) => void | Called if submission fails |
Theming
Control the appearance using the theme prop and custom CSS classes.
<FormWidget formId="your-form-id" theme="dark" className="my-custom-form" />
TypeScript support
The package includes TypeScript definitions. Import types for full type safety.
import type { FormWidgetProps, SurveyWidgetProps } from '@askusers/widget-react';
const formProps: FormWidgetProps = {
formId: 'my-form-id',
theme: 'auto',
onSubmitSuccess: () => console.log('Success!'),
};Next.js integration
For Next.js App Router, use 'use client' directive since the widgets use browser APIs.
'use client';
import { FormWidget } from '@askusers/widget-react';
import '@askusers/widget-react/styles';
export default function FeedbackForm() {
return (
<FormWidget
formId="your-form-id"
theme="auto"
/>
);
}Note: The 'use client' directive is required because the widget uses browser APIs like localStorage and window.