Widgets
Add widgets by responsibility: language and theme controls belong in the header, search owns query entry, and ScrollToTop belongs on long content pages. The components do not provide routing or search-index logic.
Language controls, search, social links, and a back-to-top button are common features of content sites. Blackwork provides separate components for these features to combine as needed.
For example, place LanguageToggle and SocialLinks in LayoutHeader, and add ScrollToTop to pages with long articles.
When to use
- Locale switching in the header
- A search field or command-palette entry
- Brand marks for GitHub, X, RSS, and similar
- Headings and body copy that match the type scale
Use lucide-react for general icons, as described in Icons. Blackwork’s built-in brand icons are available through SocialLink.
Language toggle
Pass a single option to options for a button, or an array for a dropdown. Handle the language route change in each option’s onClick callback.
Language toggle
LanguageToggle
| Prop | Type | Default | Description |
|---|---|---|---|
optionsrequired | LanguageToggleOption | LanguageToggleOption[] | — | One option renders a button. An array renders a dropdown. |
defaultValue | string | — | Current locale. Used to pick the trigger icon. |
title | string | — | Tooltip on the trigger. |
ariaLabel | string | — | Accessible name. Falls back to title. |
Search input
SearchInput provides input styling with a search icon. Connect query, submission, or filtering logic in the app.
Search input
SearchInput
| Prop | Type | Default | Description |
|---|---|---|---|
placeholder | string | "Search..." | Native input placeholder. |
inputRef | RefObject<HTMLInputElement> | — | Ref for the inner input. |
inputClassName | string | — | Classes for the inner input. |
searchIconClassName | string | — | Classes for the search icon. |
Social links
Social links
SocialLink
| Prop | Type | Default | Description |
|---|---|---|---|
typerequired | "github" | "x" | "twitter" | "instagram" | "zhihu" | "rss" | — | Built-in brand mark. Other types render nothing. |
linkrequired | string | — | Destination URL. Opens in a new tab. |
label | string | — | Tooltip. Defaults to the brand name. |
ariaLabel | string | — | Accessible name. Defaults to Visit {label} in a new tab. |
Scroll to top
ScrollToTop is fixed to the bottom-right of the viewport by default. Set ariaLabel to give the icon-only button an accessible name.
Scroll to top
ScrollToTop
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Tooltip on the button. |
ariaLabel | string | — | Accessible name for the icon-only button. |
variant | Button variant | "ghost" | Passed through to Button. |
Typography
Heading maps level to h1–h4. Paragraph is the matching body style.
Typography
Section title
Body copy for a content page.
Heading
| Prop | Type | Default | Description |
|---|---|---|---|
level | 1 | 2 | 3 | 4 | 1 | Renders h1 through h4 with the matching type scale. |
External link
ExternalLink opens links in a new tab with rel="nofollow noopener noreferrer".
External link
Quick search
Use QuickSearchDialog and its related components to build a search dialog. useQuickSearchState toggles the dialog with ⌘K / Ctrl+K. This site’s header search uses the same components. The preview below opens from a button to avoid conflicting with the site’s search shortcut.
Quick search
Notes
SocialLinksupports the typesgithub,x,twitter,instagram,zhihu, andrss.ScrollToTopusesposition: fixedby default. Override its positioning withclassNameto display it inside a preview container.
Glass appearance
Set variant="glass" on controls placed in a glass header. For the header surface and quick-search dialog, see Liquid glass.