Maofeng
99 lines
3.1 KiB
Plaintext
99 lines
3.1 KiB
Plaintext
---
|
|
title: Responsive and interaction hooks
|
|
description: Synchronize breakpoints when behavior must follow the viewport and add ripple feedback to custom controls.
|
|
order: 20
|
|
toc:
|
|
- id: breakpoint-contract
|
|
title: Breakpoint contract
|
|
- id: reading-breakpoints
|
|
title: Read breakpoints
|
|
- id: root-classes
|
|
title: Root classes
|
|
- id: server-rendering
|
|
title: Server rendering
|
|
- id: ripple
|
|
title: Ripple interaction
|
|
---
|
|
|
|
## Breakpoint contract {#breakpoint-contract}
|
|
|
|
The shared breakpoint splits the viewport into three ranges:
|
|
|
|
| Value | Range |
|
|
| --------- | -------------------- |
|
|
| `mobile` | Below 768px |
|
|
| `tablet` | 768px through 1023px |
|
|
| `desktop` | 1024px and above |
|
|
|
|
Prefer CSS for visual changes. Read a breakpoint during rendering only when mounted content, interaction behavior, or data volume must change.
|
|
|
|
## Read breakpoints {#reading-breakpoints}
|
|
|
|
```tsx
|
|
import {
|
|
useBreakpoint,
|
|
useIsDesktop,
|
|
useIsMobile,
|
|
useIsTablet,
|
|
useOnBreakpoint,
|
|
} from "@workspace/ui/hooks/use-breakpoint"
|
|
|
|
const breakpoint = useBreakpoint()
|
|
const isMobile = useIsMobile()
|
|
```
|
|
|
|
Every hook subscribes to the same pair of `matchMedia` queries through `useSyncExternalStore`. `useOnBreakpoint(listener)` runs only after the breakpoint changes; it does not report the initial value as a change.
|
|
|
|
## Root classes {#root-classes}
|
|
|
|
After mounting `BreakpointReactor`, the document root has exactly one of `.ui:mobile`, `.ui:tablet`, or `.ui:desktop`:
|
|
|
|
```tsx
|
|
import { BreakpointReactor } from "@workspace/ui/hooks/use-breakpoint"
|
|
|
|
;<>
|
|
<BreakpointReactor />
|
|
<App />
|
|
</>
|
|
```
|
|
|
|
`globals.css` registers these as the custom `mobile:`, `tablet:`, and `desktop:` variants, allowing CSS and behavioral code to share the same three-range definition.
|
|
|
|
## Server rendering {#server-rendering}
|
|
|
|
The server snapshot is fixed to `desktop` so SSR remains deterministic. To write the real class before hydration, place the result of `getBreakpointInitializationScript()` in an inline script in the document head:
|
|
|
|
```tsx
|
|
import { getBreakpointInitializationScript } from "@workspace/ui/hooks/use-breakpoint"
|
|
|
|
;<script
|
|
dangerouslySetInnerHTML={{ __html: getBreakpointInitializationScript() }}
|
|
/>
|
|
```
|
|
|
|
Pass the application's nonce under a strict CSP. The script only synchronizes the initial class; it does not replace `BreakpointReactor` for later viewport changes.
|
|
|
|
## Ripple interaction {#ripple}
|
|
|
|
`Button` already uses `useRippleRef`, so ordinary buttons need no extra setup. Use the hook directly for a custom interactive surface:
|
|
|
|
```tsx
|
|
import { useRipple } from "@workspace/ui/hooks/use-ripple"
|
|
|
|
export function Tile() {
|
|
const ref = useRipple<HTMLButtonElement>({
|
|
duration: 500,
|
|
opacity: 0.2,
|
|
rippleClassName: "bg-primary",
|
|
})
|
|
|
|
return (
|
|
<button ref={ref} className="relative">
|
|
Open project
|
|
</button>
|
|
)
|
|
}
|
|
```
|
|
|
|
The element must establish a positioned containing block, normally with `relative`. The hook ignores disabled controls, `aria-disabled="true"`, and non-primary mouse buttons, and removes listeners and animation nodes when the ref changes or unmounts. Use `useRippleRef(ref, options)` when merging an external ref.
|