Skip to main content

​
Overview

The Stringboot Web SDK provides six React hooks for seamless integration with your React application. These hooks handle initialization, string fetching, language management, and automatic updates.

​
Available Hooks

HookPurpose
useStringBootInitialize the SDK
useStringFetch a single string
useStringsFetch multiple strings
useLanguageGet/set current language
useActiveLanguagesGet available languages
useSyncManual synchronization

​
Getting Started

​
Initialize the SDK

Use useStringBoot in your root component to initialize the SDK: 
import { useStringBoot } from '@stringboot/web-sdk/react';

export function App() {
  const { initialized, error } = useStringBoot({
    apiToken: import.meta.env.VITE_STRINGBOOT_TOKEN,
    baseUrl: 'https://api.stringboot.com',
    defaultLanguage: 'en',
    debug: false
  });

  if (!initialized) return <LoadingScreen />;
  if (error) return <ErrorScreen error={error} />;

  return <MainApp />;
}
Always check initialized and error states before rendering components that use other Stringboot hooks.

​
useString Hook

Fetch a single string that automatically updates when the language changes: 
import { useString } from '@stringboot/web-sdk/react';

function Header() {
  const title = useString('app_title');
  const subtitle = useString('app_subtitle');

  return (
    <header>
      <h1>{title}</h1>
      <p>{subtitle}</p>
    </header>
  );
}
useString automatically re-renders your component when the language changes. No additional code needed.

​
useStrings Hook

Fetch multiple strings efficiently with a single hook: 
import { useStrings } from '@stringboot/web-sdk/react';

function ProductCard() {
  const strings = useStrings([
    'product_title',
    'product_description',
    'add_to_cart',
    'view_details'
  ]);

  return (
    <div className="product-card">
      <h3>{strings.product_title}</h3>
      <p>{strings.product_description}</p>
      <button>{strings.add_to_cart}</button>
      <a href="/details">{strings.view_details}</a>
    </div>
  );
}
useStrings is more efficient than multiple useString calls when fetching related strings.

​
useLanguage Hook

Get and set the current language: 
import { useLanguage } from '@stringboot/web-sdk/react';

function LanguageSelector() {
  const [currentLang, setLanguage] = useLanguage();

  return (
    <select value={currentLang} onChange={(e) => setLanguage(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
      <option value="fr">Français</option>
    </select>
  );
}

​
useActiveLanguages Hook

Get the list of available languages from your Stringboot project: 
import { useLanguage, useActiveLanguages } from '@stringboot/web-sdk/react';

function LanguageSwitcher() {
  const [currentLang, setLanguage] = useLanguage();
  const { languages, loading, error } = useActiveLanguages();

  if (loading) return <div>Loading languages...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <select value={currentLang} onChange={(e) => setLanguage(e.target.value)}>
      {languages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.name}
        </option>
      ))}
    </select>
  );
}
Returns:
  • languages - Array of { code, name } objects
  • loading - Boolean loading state
  • error - Error message if request fails

​
useSync Hook

Manually trigger synchronization with the server: 
import { useSync } from '@stringboot/web-sdk/react';

function SyncButton() {
  const { sync, syncing } = useSync();

  return (
    <button onClick={() => sync()} disabled={syncing}>
      {syncing ? 'Syncing...' : 'Sync Strings'}
    </button>
  );
}

​
Complete Example

Here’s a full React application using all the hooks: 
import React from 'react';
import {
  useStringBoot,
  useString,
  useStrings,
  useLanguage,
  useActiveLanguages,
} from '@stringboot/web-sdk/react';

export function App() {
  const { initialized, error } = useStringBoot({
    apiToken: import.meta.env.VITE_STRINGBOOT_TOKEN,
    baseUrl: 'https://api.stringboot.com',
    defaultLanguage: 'en',
    debug: false
  });

  if (!initialized) return <LoadingScreen />;
  if (error) return <ErrorScreen error={error} />;

  return <MainApp />;
}

function MainApp() {
  return (
    <div className="app">
      <Header />
      <LanguageSwitcher />
      <Content />
    </div>
  );
}

function Header() {
  const title = useString('app_title');
  return <h1>{title}</h1>;
}

function LanguageSwitcher() {
  const [currentLang, setLanguage] = useLanguage();
  const { languages, loading } = useActiveLanguages();

  if (loading) return null;

  return (
    <select value={currentLang} onChange={(e) => setLanguage(e.target.value)}>
      {languages.map((lang) => (
        <option key={lang.code} value={lang.code}>
          {lang.name}
        </option>
      ))}
    </select>
  );
}

function Content() {
  const strings = useStrings([
    'welcome_message',
    'description',
    'cta_button'
  ]);

  return (
    <main>
      <h2>{strings.welcome_message}</h2>
      <p>{strings.description}</p>
      <button>{strings.cta_button}</button>
    </main>
  );
}

​
Advanced Usage

​
String Interpolation

Replace placeholders in your strings: 
import { useString } from '@stringboot/web-sdk/react';

function Greeting({ userName }) {
  const template = useString('greeting_template'); // "Hello, {name}!"
  const greeting = template.replace('{name}', userName);

  return <h2>{greeting}</h2>;
}

​
Conditional Rendering

Use string values for feature flags or conditional content: 
import { useString } from '@stringboot/web-sdk/react';

function FeatureToggle() {
  const featureEnabled = useString('show_new_feature');

  return (
    <div>
      {featureEnabled === 'true' && <NewFeature />}
    </div>
  );
}

​
Fallback Values

Provide default values for missing strings: 
import { useString } from '@stringboot/web-sdk/react';

function SafeComponent() {
  const title = useString('page_title') || 'Default Title';

  return <h1>{title}</h1>;
}

​
Best Practices

Always use useStringBoot in your root component before any other hooks.
Check initialized before rendering components that use string hooks.
Use useStrings instead of multiple useString calls when fetching related strings.
Always provide default values for critical strings using the || operator.

​
What’s Next?

Usage Guide

Learn vanilla JavaScript patterns

Best Practices

Production-ready patterns and tips