11---
22title : Translation Widget
3- description : Side-by-side translation view with an editable target pane, RTL-aware layout , and soft claymorphism styling. Controlled and uncontrolled modes built in .
3+ description : Side-by-side translation card with language pickers, swap, copy, character count , and a loading state. RTL-aware and themed with shadcn tokens .
44---
55
66import { PreviewComponents } from " @/components/docs/preview-components" ;
@@ -94,28 +94,36 @@ export function Translate() {
9494
9595## Props
9696
97- | Prop | Type | Required | Description |
98- | ---------------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------- |
99- | ` locales ` | ` Locale[] ` | No | Locales for the per-pane language pickers; omit to show static chips |
100- | ` sourceLocale ` | ` string ` | No | BCP 47 code of the source locale (e.g. ` "en" ` ); provide to control it |
101- | ` defaultSourceLocale ` | ` string ` | No | Initial source locale when uncontrolled (default: ` locales[0] ` , else ` "en" ` ) |
102- | ` onSourceLocaleChange ` | ` (code: string) => void ` | No | Callback when the source locale changes |
103- | ` targetLocale ` | ` string ` | No | BCP 47 code of the target locale (e.g. ` "fr" ` , ` "ar" ` ); provide to control it |
104- | ` defaultTargetLocale ` | ` string ` | No | Initial target locale when uncontrolled (default: ` locales[1] ` , else ` "en" ` ) |
105- | ` onTargetLocaleChange ` | ` (code: string) => void ` | No | Callback when the target locale changes |
106- | ` sourceText ` | ` string ` | No | Source text — pass this to control the source pane |
107- | ` onSourceChange ` | ` (text: string) => void ` | No | Callback when the source text changes; makes the pane editable |
108- | ` targetText ` | ` string ` | No | Target text — pass this to control the target pane (read-only without ` onTargetChange ` ) |
109- | ` defaultTargetText ` | ` string ` | No | Initial target text when uncontrolled |
110- | ` onTargetChange ` | ` (text: string) => void ` | No | Callback when the target text changes |
111- | ` onSwap ` | ` () => void ` | No | Called after the swap button exchanges locales and texts |
112- | ` sourcePlaceholder ` | ` string ` | No | Placeholder for the source pane |
113- | ` targetPlaceholder ` | ` string ` | No | Placeholder for the target pane |
114- | ` sourceLabel ` | ` string ` | No | Accessible label for the source pane (default: ` "Source text" ` ) |
115- | ` targetLabel ` | ` string ` | No | Accessible label for the target pane (default: ` "Target text" ` ) |
116- | ` readOnlySource ` | ` boolean ` | No | Keep the source pane read-only even with ` onSourceChange ` |
117- | ` dir ` | ` "ltr" \| "rtl" ` | No | Override the auto-detected layout direction |
118- | ` className ` | ` string ` | No | Additional CSS classes |
97+ | Prop | Type | Required | Description |
98+ | ---------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------- |
99+ | ` locales ` | ` Locale[] ` | No | Locales for the per-pane language pickers; omit to show static chips |
100+ | ` sourceLocale ` | ` string ` | No | BCP 47 code of the source locale (e.g. ` "en" ` ); provide to control it |
101+ | ` defaultSourceLocale ` | ` string ` | No | Initial source locale when uncontrolled (default: ` locales[0] ` , else ` "en" ` ) |
102+ | ` onSourceLocaleChange ` | ` (code: string) => void ` | No | Callback when the source locale changes |
103+ | ` targetLocale ` | ` string ` | No | BCP 47 code of the target locale (e.g. ` "fr" ` , ` "ar" ` ); provide to control it |
104+ | ` defaultTargetLocale ` | ` string ` | No | Initial target locale when uncontrolled (default: ` locales[1] ` , else ` "en" ` ) |
105+ | ` onTargetLocaleChange ` | ` (code: string) => void ` | No | Callback when the target locale changes |
106+ | ` sourceText ` | ` string ` | No | Source text — pass this to control the source pane |
107+ | ` defaultSourceText ` | ` string ` | No | Initial source text when uncontrolled |
108+ | ` onSourceChange ` | ` (text: string) => void ` | No | Callback when the source text changes; makes the pane editable |
109+ | ` targetText ` | ` string ` | No | Target text — pass this to control the target pane (read-only without ` onTargetChange ` ) |
110+ | ` defaultTargetText ` | ` string ` | No | Initial target text when uncontrolled |
111+ | ` onTargetChange ` | ` (text: string) => void ` | No | Callback when the target text changes |
112+ | ` onSwap ` | ` () => void ` | No | Called after the swap button exchanges locales and texts |
113+ | ` sourcePlaceholder ` | ` string ` | No | Placeholder for the source pane |
114+ | ` targetPlaceholder ` | ` string ` | No | Placeholder for the target pane |
115+ | ` sourceLabel ` | ` string ` | No | Accessible label for the source pane (default: ` "Source text" ` ) |
116+ | ` targetLabel ` | ` string ` | No | Accessible label for the target pane (default: ` "Target text" ` ) |
117+ | ` readOnlySource ` | ` boolean ` | No | Keep the source pane read-only even with ` onSourceChange ` |
118+ | ` showCount ` | ` boolean ` | No | Show the source character count (default: ` true ` ) |
119+ | ` maxLength ` | ` number ` | No | Character limit for both panes; the count shows ` n / max ` |
120+ | ` showClear ` | ` boolean ` | No | Show a clear button under an editable source (default: ` true ` ) |
121+ | ` showCopy ` | ` boolean ` | No | Show a copy-to-clipboard button under the target (default: ` true ` ) |
122+ | ` onTargetCopy ` | ` (text: string) => void ` | No | Called with the target text after it is copied |
123+ | ` loading ` | ` boolean ` | No | Show a skeleton in the target pane and mark it ` aria-busy ` |
124+ | ` classNames ` | ` TranslationWidgetClassNames ` | No | Per-part class overrides: ` root ` , ` header ` , ` pane ` , ` textarea ` , ` footer ` , ` swap ` , ` chip ` |
125+ | ` dir ` | ` "ltr" \| "rtl" ` | No | Override the auto-detected layout direction |
126+ | ` className ` | ` string ` | No | Additional CSS classes |
119127
120128Any other prop — ` id ` , ` data-* ` , ` aria-* ` — is spread onto the root element, and the
121129ref is forwarded to it.
@@ -178,8 +186,8 @@ or controlled (`sourceLocale` + `onSourceLocaleChange`, same for the target). Wh
178186## Swap
179187
180188The swap button between the panes exchanges ** both** the locales and the texts —
181- source ↔ target — and fires ` onSwap ` . The icon points sideways (⇄) when the panes
182- sit side by side and rotates to ↕ when they stack on narrow screens . The button
189+ source ↔ target — and fires ` onSwap ` . It sits in the header bar between the two
190+ language pickers, and its icon spins half a turn on every swap . The button
183191carries an ` aria-label="Swap languages" ` and is disabled when any exchanged value
184192is controlled without a change handler, since the swap could not be applied:
185193
@@ -198,6 +206,59 @@ is controlled without a change handler, since the swap could not be applied:
198206/>
199207```
200208
209+ ## Toolbar
210+
211+ Each pane ends in a small toolbar. The source shows a live character count —
212+ ` n / max ` when you pass ` maxLength ` , turning destructive at the limit — and a clear
213+ button when the pane is editable. The target has a copy button that confirms with a
214+ check and announces "Translation copied to clipboard" to screen readers:
215+
216+ ``` tsx
217+ <TranslationWidget
218+ sourceLocale = " en"
219+ targetLocale = " fr"
220+ sourceText = { source }
221+ onSourceChange = { setSource }
222+ maxLength = { 500 }
223+ onTargetCopy = { (text ) => analytics .track (" translation-copied" , { length: text .length })}
224+ />
225+ ```
226+
227+ Turn any of it off with ` showCount={false} ` , ` showClear={false} ` or ` showCopy={false} ` .
228+
229+ ## Loading state
230+
231+ While a translation is in flight, pass ` loading ` to replace the target text with a
232+ pulsing skeleton. The textarea is marked ` aria-busy ` and copying is disabled:
233+
234+ ``` tsx
235+ const [loading, setLoading] = useState (false );
236+
237+ async function translate(text : string ) {
238+ setLoading (true );
239+ setTarget (await api .translate (text , targetLocale ));
240+ setLoading (false );
241+ }
242+
243+ <TranslationWidget loading = { loading } /* … */ />;
244+ ```
245+
246+ ## Customization
247+
248+ Every part takes extra classes through ` classNames ` , merged after the defaults with
249+ ` cn ` , so your classes win:
250+
251+ ``` tsx
252+ <TranslationWidget
253+ classNames = { {
254+ root: " rounded-2xl shadow-lg" ,
255+ header: " bg-muted/50" ,
256+ textarea: " font-serif text-lg" ,
257+ swap: " bg-primary text-primary-foreground" ,
258+ }}
259+ />
260+ ```
261+
201262## RTL support
202263
203264When the target locale is an RTL language (` ar ` , ` he ` , ` fa ` , ` ur ` , …) or carries an
@@ -212,29 +273,33 @@ Pass `dir` to set the widget's direction explicitly.
212273
213274## Features
214275
215- - ** Side-by-side panes** — source and target text areas in one responsive row
276+ - ** Side-by-side panes** — source and target in one card, stacked on narrow screens
216277- ** Language pickers** — pass ` locales ` for a Language Switcher per pane; static chips otherwise
217278- ** Swap button** — exchanges both locales and texts, with ` onSwap ` and an accessible label
218279- ** Editable target** — uncontrolled, or controlled with ` targetText ` + ` onTargetChange ` (a controlled target without a handler renders read-only so typed text is never silently dropped)
219280- ** RTL-aware** — per-pane ` dir ` and ` lang ` follow each locale; pane order stays fixed
220- - ** Accessible** — labelled textareas, ` lang ` attributes, visible focus rings
281+ - ** Toolbar** — character count with ` maxLength ` , clear, and copy-to-clipboard
282+ - ** Loading state** — skeleton target pane with ` aria-busy `
283+ - ** Accessible** — labelled textareas, ` lang ` attributes, visible focus rings, live copy announcement
221284- ** Keyboard support** — Tab between panes, type to translate
222- - ** Claymorphism styling** — soft raised card with recessed, pressed-in textareas
223- - ** Dark mode** — built with Tailwind CSS, dark-mode compatible
285+ - ** Themeable** — shadcn tokens (` bg-card ` , ` border ` , ` muted ` , ` ring ` ), so it follows your theme and dark mode
286+ - ** Customizable** — ` classNames ` for every part
287+ - ** Motion** — spring swap icon and copy confirmation, respecting reduced-motion settings
224288- ** Controlled/uncontrolled** — works with or without ` targetText ` ; same for locales
225289
226290## Design
227291
228- The widget uses a claymorphism treatment: a large-radius card with a soft drop
229- shadow and an inner top highlight, and textareas that read as recessed via an
230- inset shadow. Colours are Tailwind utilities — no CSS-variable tokens — so the
231- component drops into any project and restyles with ` className ` .
292+ One card, split into a source pane and a slightly tinted target pane, with both
293+ language pickers and the swap button in a shared header bar — the layout people
294+ know from translation tools. Colors come from shadcn's semantic tokens, so the
295+ widget takes on your theme, radius and dark mode without extra configuration .
232296
233297## Dependencies
234298
235299This component uses:
236300
237301- ` clsx ` and ` tailwind-merge ` (bundled as dependencies)
302+ - ` lucide-react ` for icons and ` motion ` for the swap and copy animations
238303- the [ Language Switcher] ( /docs/components/language-switchers/language-switcher ) component (pulled in automatically via registry dependencies)
239304
240305Peer dependencies:
0 commit comments