Silk

https://silkhq.com/docs
Admin
Silk is a React component library for building advanced swipeable modal and overlay components like...
Tokens:42,196
Snippets:348
Trust Score:5.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Silk package

Source: https://silkhq.com/docs/getting-started.md

Install the Silk components package using npm.

```bash
npm install @silk-hq/components
```

--------------------------------

### Function syntax with progress example

Source: https://silkhq.com/docs/sheet.md

Example using the function syntax with progress to animate translateX.

```tsx
<Sheet.Outlet stackingAnimation={{ translateX: ({ progress }) => progress * 100 + "px", }} />
```

--------------------------------

### useClientMediaQuery usage example

Source: https://silkhq.com/docs/use-client-media-query.md

Call the hook with a CSS media query string to get a boolean state indicating whether the query matches. The hook updates when the match changes and returns false on the server.

```tsx
const largeViewport = useClientMediaQuery("(min-width: 500px)");
```

--------------------------------

### Function syntax with tween example

Source: https://silkhq.com/docs/sheet.md

Example using the function syntax with tween to animate backgroundColor.

```tsx
<Sheet.Outlet stackingAnimation={{ backgroundColor: ({ tween }) => `rgb(${tween(10, 0)}, ${tween(10, 0)}, ${tween(10, 0)})`, }}/>
```

--------------------------------

### onScrollStart

Source: https://silkhq.com/docs/scroll.md

Documentation for the onScrollStart event handler prop, including its type, default value, and usage examples.

```APIDOC
## onScrollStart

### Description
An event handler that runs when scrolling starts, whether it is initiated by a scroll gesture or programmatically. The underlying custom event has a default behavior that can be changed either by calling its `changeDefault` method with an option object as parameter, or by directly passing the option object to the prop.

### Type
`ts:{ dismissKeyboard: boolean } | ((customEvent: ScrollStartCustomEvent) => void)` where `ScrollStartCustomEvent` is `ts:{ changeDefault: (changedBehavior: { dismissKeyboard: boolean; }) => void; dismissKeyboard: boolean; nativeEvent: null; }`

### Default
`{ dismissKeyboard: false }`

### Values
- `{ dismissKeyboard: true }` - Causes the on-screen keyboard to be dismissed if it is presented when the event is fired.
- `{ dismissKeyboard: false }` - Inverse of `{ dismissKeyboard: true }`.

### Example
```tsx
<Scroll.View onFocusInside={{ dismissKeyboard: true }}>
	...
</Scroll.View>
```

```tsx
<Sheet.View
  onFocusInside={(event) => event.changeDefault({ dismissKeyboard: true })}
 >
	...
</Sheet.View>
```
```

--------------------------------

### Set initial detent index with defaultActiveDetent

Source: https://silkhq.com/docs/sheet.md

Provides an example of setting the defaultActiveDetent prop to 2, which defines the initial detent index the Sheet rests on after presentation. Detent indexes start at 0 when fully outside, intermediate detents from 1 to n-1, and the last detent when fully expanded.

```tsx
<Sheet.Root defaultActiveDetent={2}>
	...
</Sheet.Root>
```

--------------------------------

### Keyframes array syntax example

Source: https://silkhq.com/docs/sheet.md

Example using the keyframes array syntax to animate translateX from 0px to 100px.

```tsx
<Sheet.Outlet stackingAnimation={{translateX: ["0px", "100px"], }} />
```

--------------------------------

### onScrollStart with direct option

Source: https://silkhq.com/docs/scroll.md

Passes { dismissKeyboard: true } directly to the onFocusInside prop to dismiss the keyboard when scrolling starts.

```tsx
<Scroll.View onFocusInside={{ dismissKeyboard: true }}>
	...
</Scroll.View>
```

--------------------------------

### onScrollStart with changeDefault method

Source: https://silkhq.com/docs/scroll.md

Uses the event's changeDefault method to set dismissKeyboard to true when scrolling starts.

```tsx
<Sheet.View
  onFocusInside={(event) => event.changeDefault({ dismissKeyboard: true })}
 >
	...
</Sheet.View>
```

--------------------------------

### Island Anatomy Example

Source: https://silkhq.com/docs/island.md

Shows the basic structure for using Island.Root and Island.Content to keep elements interactive outside a Sheet with inertOutside enabled.

```tsx
import { Sheet, Island } from "@silk-hq/components";

export default () => (
   <>
      <Island.Root>
         <Island.Content>
            {* Interactive content *}
         </Island.Content>
      </Island.Root>

      <Sheet.Root>
         <Sheet.Trigger />
         <Sheet.Portal>
            <Sheet.View inertOutside={true}>
               <Sheet.Backdrop />
               <Sheet.Content>
                  {* Interactive content *}
               </Sheet.Content>
            </Sheet.View>
         </Sheet.Portal>
      </Sheet.Root>
   </>
);
```

--------------------------------

### Example usage of --silk-100-lvh-dvh-pct

Source: https://silkhq.com/docs/styling.md

Shows how to use the custom property to set the height of an element, typically on Scroll.View's underlying element, to compensate for the iOS SFSafariViewController viewport height bug.

```css
.MySheet_view {
	height: var(--silk-100-lvh-dvh-pct);
}
```

--------------------------------

### Function syntax with tween for backgroundColor in stackingAnimation

Source: https://silkhq.com/docs/sheet-stack.md

Uses the function syntax with the tween helper to interpolate RGB values from 10 to 0 as sheets stack. The tween function takes start and end values and returns a string.

```tsx
<SheetStack.Outlet
	stackingAnimation={{
		backgroundColor:
			({ tween }) =>
				`rgb(${tween(10, 0)}, ${tween(10, 0)}, ${tween(10, 0)})`,
	}}
/>
```

--------------------------------

### VisuallyHidden.Root

Source: https://silkhq.com/docs/visually-hidden.md

Documentation for the VisuallyHidden.Root component, including its props and usage notes.

```APIDOC
## VisuallyHidden.Root

### Description
A component that visually hides elements and their content but keeps them accessible to screen-readers. The Root sub-component wraps content to be made visually hidden.

### Component
`<VisuallyHidden.Root>`

### Props

#### `asChild`
- **Type**: `boolean | undefined`
- **Default**: `undefined`
- **Description**: Defines whether the sub-component underlying element is the default one or the one passed as child of the sub-component.

##### Values
- `true`: The underlying element rendered is the child.
- `false | undefined`: The underlying element rendered is the default one.

### Notes
- If the child is a React component rendering an element:
  - it must accept props and spread all received props onto the rendered element;
  - in React < 19, it must use `React.forwardRef()` and pass the received ref to the rendered element.
- See [Composition](https://silkhq.com/docs/composition.md) for more information.
```

--------------------------------

### getDistance

Source: https://silkhq.com/docs/scroll.md

Returns the distance in pixels traveled by Scroll.Content from its start position.

```APIDOC
## getDistance

### Description
Returns the distance in pixels traveled by `<Scroll.Content>` from its start position.

### Method
N/A (Imperative method on Scroll component ref)

### Endpoint
N/A (Imperative method on Scroll component ref)

### Parameters
None

### Response
#### Success Response
- **Type**: `() => number`
- **Returns**: number - Distance in pixels traveled from start position

#### Response Example
```ts
const distance = scrollRef.current.getDistance();
```
```

--------------------------------

### Disable auto-focus on Sheet dismissal with onDismissAutoFocus

Source: https://silkhq.com/docs/sheet.md

Two ways to disable auto-focus when the Sheet is dismissed: pass an option object directly to the prop, or use the event's changeDefault method. The first example sets focus to false, preventing any element from receiving focus. The second example uses the event parameter to call changeDefault with the same option.

```tsx
<Sheet.View onDismissAutoFocus={{ focus: false }}>
	...
</Sheet.View>
```

```tsx
<Sheet.View
  onDismissAutoFocus={(event) => event.changeDefault({ focus: false })}
 >
	...
</Sheet.View>
```

--------------------------------

### useThemeColorDimmingOverlay hook usage

Source: https://silkhq.com/docs/use-theme-color-dimming-overlay.md

Initializes the hook with an element reference and a dimming color, then sets the overlay opacity to 0.5 and animates it from 0 to 0.5 using keyframes.

```tsx
const { setDimmingOverlayOpacity, animateDimmingOverlayOpacity } =
  useThemeColorDimmingOverlay({
      elementRef: stackBackgroundRef,
      dimmingColor: "rgb(0, 0, 0)",
  });

setDimmingOverlayOpacity(0.5);
animateDimmingOverlayOpacity({ keyframes: [0, 0.5] });
```

--------------------------------

### Wrap third-party overlay in ExternalOverlay.Root

Source: https://silkhq.com/docs/third-party-overlays.md

Wrap a third-party overlay in <ExternalOverlay.Root> to make it part of the frontmost presented Sheet when automatic detection fails. Use asChild to merge with the overlay's content element.

```tsx
import { Menu } from "third-party-lib";
import { ExternalOverlay } from "@silk-hq/components";

const MyMenu = () => (
	<Menu.Root>
	   <Menu.Portal>
	      <ExternalOverlay.Root asChild>
	         <Menu.Content>
	            ...
	         </Menu.Content>
	      </ExternalOverlay.Root>
	   </Menu.Portal>
	</Menu.Root>
);
```

--------------------------------

### Step down with Sheet.Trigger

Source: https://silkhq.com/docs/sheet.md

Example of a Sheet.Trigger that steps the sheet down by one detent when pressed, with forceFocus disabled. The action type is 'step' and direction 'down'. The onPress prop sets forceFocus to false.

```tsx
const MyTrigger = () => (
	<Sheet.Trigger
		action={{ type: "step", direction: "down" }}
		onPress={{ forceFocus: false }}
	>
		Step down
	</Sheet.Trigger>
)
```

--------------------------------

### <Sheet.View>

Source: https://silkhq.com/docs/sheet.md

Documentation for the Sheet.View sub-component, including its properties and behavior.

```APIDOC
## <Sheet.View>

### Description

The View sub-component underlying element is the view inside of which the <Sheet.Content> underlying element can travel. It also holds the HTML `role` attribute for the Sheet.

### Properties

#### `forComponent`

- **Type**: `SheetId`
- **Presence**: Optional
- **Default**: The `SheetId` of the closest `<Sheet.Root>` ancestor.

Associates this sub-component with the desired Sheet instance.

#### `contentPlacement`

- **Type**: `"top" | "bottom" | "left" | "right" | "center"`
- **Presence**: Optional
- **Default**: `"bottom"` if `tracks` is not set, otherwise it matches the value of the `tracks` prop.

Defines the placement of `<Sheet.Content>` inside of `<Sheet.View>` on the travel axis. On the cross axis, it is always centered.

#### `tracks`

- **Type**: `"top" | "bottom" | "left" | "right" | ["top", "bottom"] | ["left", "right"]`
- **Presence**: Optional
- **Default**: `"bottom"` if `contentPlacement` is not set, otherwise it matches the value of the `contentPlacement`.

Defines the track(s) `<Sheet.Content>` can travel on, from its last detent (index `n`) to its origin detent (index `0`).

#### `detents`

- **Type**: `string | Array<string>` where `string` is a CSS length which does not use the `%` unit.
- **Presence**: Optional
- **Default**: `undefined`

Defines one or several intermediate detents on which `<Sheet.Content>` can rest on the track between the origin detent (index `0`) and the last detent (index `n`).

#### `swipeTrap`

- **Type**: `boolean | { x?: boolean; y?: boolean }`
- **Presence**: Optional
- **Default**: `{ x: true, y: false }` on Android in non-standalone mode, `true` otherwise.

Defines whether swipes on the specified axis or axes are trapped within `<Sheet.View>` or not.

When not trapped, when swiping in a direction where further travel is not possible, the swipe will propagate to the closest ancestor Sheet, scroll container, or window (triggering swipe to go back in history in browsers that support it).

##### Values description

| Value         | Description                                |
| ------------- | ------------------------------------------ |
| `true`        | Traps swipe both on both the x and y axis. |
| `{ x: true }` | Traps swipe on the x axis.                 |
| `{ y: true }` | Traps swipe on the y axis.                 |

##### Notes

- Always computes to `true` if `inertOutside` is set to `true`.
- On Android in non-standalone mode, `swipeTrap` on the y axis always computes to `false` not to prevent the browser UI from being revealed.
- If `swipeOvershoot` is set to `false`, `swipeTrap` on the travel axis always computes to `true`.
- Safari has a bug causing swipe to always be trapped when swiping over a vertically swipeable Sheet or Scroll which is inside of a horizontally swipeable Sheet or Scroll (and vice versa). We hope to see that issue resolved quickly.
```

--------------------------------

### Keys supporting keyframes array syntax in stackingAnimation

Source: https://silkhq.com/docs/sheet-stack.md

Lists the keys that support the keyframes array syntax. Apart from opacity, all keys are incorporated into a single transform declaration.

```tsx
| "opacity"
| "translate"
| "translateX"
| "translateY"
| "translateZ"
| "scale"
| "scaleX"
| "scaleY"
| "scaleZ"
| "rotate"
| "rotateX"
| "rotateY"
| "rotateZ"
| "skew"
| "skewX"
| "skewY"
```

--------------------------------

### Use contentGetter with a function

Source: https://silkhq.com/docs/third-party-overlays.md

Use the contentGetter prop with a function that returns the overlay element, useful when the overlay is referenced via a ref.

```tsx
import { Sheet, ExternalOverlay } from "@silk-hq/components";

const BottomSheet = ({ chatPluginRef }) => (
	<Sheet.Root>
		<Sheet.Trigger>Open</Sheet.Trigger>
		<Sheet.Portal>
			<Sheet.View>
				<Sheet.Backdrop />
				<Sheet.Content>
					...
					<ExternalOverlay.Root contentGetter={() => chatPluginRef.current} />
				</Sheet.Content>
			</Sheet.View>
		</Sheet.Portal>
  </Sheet.Root>
);
```

--------------------------------

### Basic Sheet Anatomy

Source: https://silkhq.com/docs/sheet.md

Basic anatomy of the Sheet component. Use this as a starting point for building a swipeable modal or non-modal overlay. It includes the required sub-components: Root, Trigger, Portal, View, Backdrop, Content, BleedingBackground, Title, and Description.

```tsx
import { Sheet } from "@silk-hq/components";

export default () => (
	<Sheet.Root>
		<Sheet.Trigger />
		<Sheet.Portal>
			<Sheet.View>
				<Sheet.Backdrop />
				<Sheet.Content>
					<Sheet.BleedingBackground />
					<Sheet.Title />
					<Sheet.Description />
				</Sheet.Content>
			</Sheet.View>
		</Sheet.Portal>
	</Sheet.Root>
);
```

--------------------------------

### Basic Fixed component usage

Source: https://silkhq.com/docs/fixed.md

Basic anatomy showing Fixed.Root wrapping Fixed.Content. Imports Fixed from @silk-hq/components. Use this as the foundation for fixed positioning. The Root and Content sub-components are required.

```tsx
import { Fixed } from "@silk-hq/components";

export default () => (
	<Fixed.Root>
		<Fixed.Content>
			...
		</Fixed.Content>
	</Fixed.Root>
);
```

--------------------------------

### onClickOutside prop examples for Sheet.View

Source: https://silkhq.com/docs/sheet.md

Two ways to set the onClickOutside prop on Sheet.View. The first passes an option object directly; the second uses the event's changeDefault method. Both prevent dismissal on outside clicks, but the second allows dynamic behavior changes.

```tsx
<Sheet.View onClickOutside={{ dismiss: false }}>
	...
</Sheet.View>
```

```tsx
<Sheet.View
  onClickOutside={(event) => event.changeDefault({ dismiss: false })}
 >
	...
</Sheet.View>
```

--------------------------------

### CSS custom property for Fixed side

Source: https://silkhq.com/docs/fixed.md

CSS example showing how to declare the --silk-fixed-side custom property when using bottom or right CSS properties without top or left. Adjust the values according to the CSS properties used. This is required to ensure correct positioning.

```css
.my-fixed-element {
	bottom: 16px;
	right: 16px;
	--silk-fixed-side: bottom right;
}
```

--------------------------------

### Sheet with SpecialWrapper

Source: https://silkhq.com/docs/sheet.md

Shows how to use Sheet.SpecialWrapper.Root and Sheet.SpecialWrapper.Content to wrap the content area. This is useful when you need a special wrapper for styling or behavior around the main content.

```tsx
import { Sheet } from "@silk-hq/components";

export default () => (
	<Sheet.Root>
		<Sheet.Trigger />
		<Sheet.Portal>
			<Sheet.View>
				<Sheet.Backdrop />
				<Sheet.Content>
					<Sheet.SpecialWrapper.Root>
						<Sheet.SpecialWrapper.Content>
							<Sheet.BleedingBackground />
							<Sheet.Title />
							<Sheet.Description />
						</Sheet.SpecialWrapper.Content>
					</Sheet.SpecialWrapper.Root>
				</Sheet.Content>
			</Sheet.View>
		</Sheet.Portal>
	</Sheet.Root>
);
```

--------------------------------

### Create and use a component instance id with createComponentId

Source: https://silkhq.com/docs/create-component-id.md

Create a component instance id with createComponentId() and pass it to the Root sub-component's componentId prop, then to the forComponent prop of a nested sub-component to associate it with the same instance. Must be called outside component functions or classes to avoid HMR issues.

```tsx
const loginSheetId = createComponentId();
```

```tsx
<Sheet.Root componentId={loginSheetId}>
	...
	<Sheet.Root>
		...
		<Sheet.Trigger forComponent={loginSheetId} />
		...
	</Sheet.Root>
	...
</Sheet.Root>
```

--------------------------------

### <Scroll.View>

Source: https://silkhq.com/docs/scroll.md

Documentation for the Scroll.View sub-component, including its props asChild and forComponent.

```APIDOC
## <Scroll.View>

### Description
The View sub-component is the area inside of which the `<Scroll.Content>` can travel.

### Notes
- Elements put directly inside of this sub-component will not move along the content as scroll occurs.
- If you are using this component inside of nested CSS grid or flex containers, you may need to add `css:min-width: 0px` and/or `css:min-height: 0px` on these containers’ children to prevent `<Scroll.View>` being sized based on `<Scroll.Content>` size on the scroll axis, thus causing visible overflow instead of a scrollable overflow.

### asChild
See [asChild](https://silkhq.com/docs/scroll.md#root-aschild) on `<Scroll.Root>`.

### forComponent

#### Presence
Optional

#### Type
`ScrollId`

#### Default
The `ScrollId` of the closest `<Scroll.Root>` ancestor.

#### Description
Associates this sub-component with the desired Scroll instance.
```

--------------------------------

### Function syntax for translateX in stackingAnimation

Source: https://silkhq.com/docs/sheet-stack.md

Uses the function syntax to animate translateX based on the progress value, which goes from 0 to the number of stacked sheets. The returned string is applied as the CSS property value.

```tsx
<SheetStack.Outlet
	stackingAnimation={{
		translateX: ({ progress }) => progress * 100 + "px",
	}}
/>
```

--------------------------------

### onScrollEnd

Source: https://silkhq.com/docs/scroll.md

Documentation for the onScrollEnd event handler prop, including its type and default value.

```APIDOC
## onScrollEnd

### Description
An event handler that runs when scrolling ends, whether it was initiated by a scroll gesture or programmatically.

### Type
`ts:({ nativeEvent: Event }) => void`

### Default
`undefined`
```

--------------------------------

### getProgress

Source: https://silkhq.com/docs/scroll.md

Returns the scroll progress from 0 to 1.

```APIDOC
## getProgress

### Description
Returns the scroll progress from 0 to 1. When `<Scroll.Content>` start edge is aligned with `<Scroll.View>` start edge, scroll progress is 0. When they are aligned on their end edge, scroll progress is 1.

### Method
N/A (Imperative method on Scroll component ref)

### Endpoint
N/A (Imperative method on Scroll component ref)

### Parameters
None

### Response
#### Success Response
- **Type**: `() => number`
- **Returns**: number - Scroll progress from 0 to 1

#### Response Example
```ts
const progress = scrollRef.current.getProgress();
```
```
Tokens:
Raw