feat(Gallery): add inline view and controlled active item index by artemnikotin · Pull Request #397 · gravity-ui/components

artemnikotin · 2026-07-06T15:17:48Z

add view prop ('modal' default | 'inline') to render the gallery in place instead of a modal
add controlled activeItemIndex / onActiveItemIndexChange,
backed by a local useConditionallyControlledState
add GalleryItem.id to keep item previews reconciled by identity

I hereby agree to the terms of the CLA available at: link.

kseniya57 · 2026-07-08T12:27:32Z

+| open                    | `Boolean`                 |          |                  |         | `modal` only. The modal opened state                                                     |
+| onOpenChange            | `(open: boolean) => void` |          |                  |         | `modal` only. The modal toggle handler                                                   |
+| container               | `HTMLElement`             |          |                  |         | `modal` only. The modal container                                                        |
+| onClose                 | `() => void`              |          |                  |         | `inline` only. Called on the header close/back button; the button is hidden when omitted |


onOpenChange and onClose: when using the component, it will seem that these props do the same thing

I think that for inline mode, onClose and rendering an additional header with a close button are unnecessary

Agree, removed.

kseniya57 · 2026-07-08T12:35:14Z

+
+```tsx
+{
+  open && (


Please remove this flag from the example, the goal here is to show that the gallery can be rendered inline, not to show how its conditional rendering can be implemented

Good catch, I forgot to remove it after the previous version.

kseniya57 · 2026-07-08T12:45:24Z

    }

+    &_view_inline {
+        position: absolute;


I don't think it's a good idea to set such position rules; they should be set by the user for a specific use case.

Agreed, styling the inline gallery's container is the consumer's responsibility. Updated.

kseniya57 · 2026-07-08T12:51:47Z

+
+export type GalleryProps = GalleryModalProps | GalleryInlineProps;
+
+function resolveViewProps(props: GalleryProps) {


Let's move this to Gallery/utils/resolveViewProps, so this file will contain only the component

But in general, this function seems to be unnecessary, because the props type already excludes the passing of unnecessary properties, and instead of isInline, it is better to use view === inline directly, as this constant does not make readability better, it is equivalent to

You're right, removed the unnecessary helpers.

kseniya57 · 2026-07-08T12:52:35Z

+ * - `modal` — open the gallery in a viewport-sized modal overlay (default).
+ * - `inline` — render the gallery in place, filling its parent container.
+ */
+export type GalleryView = 'modal' | 'inline';


Let's move this to Gallery/types.ts

kseniya57 · 2026-07-08T13:01:35Z

-    }, [onOpenChange]);
-
    const handleClose = React.useCallback(() => {
+        if (isInline) {


This is superfluous when we remove onClose.

gravity-ui-bot · 2026-07-09T04:44:51Z

Preview is ready.

kseniya57 · 2026-07-10T10:44:43Z

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+// Copied from `@gravity-ui/uikit`'s private `useStateWithCallback` hook:


I think we don't need this information

I see, replaced with hook description.

kseniya57 · 2026-07-10T10:44:57Z

+
+import {useStateWithCallback} from '../useStateWithCallback';
+
+// Copied from `@gravity-ui/uikit`'s private `useConditionallyControlledState` hook:


I think we don't need this information

I see, replaced with hook description.

kseniya57 · 2026-07-10T10:48:48Z

+        open,
+        onOpenChange,
+        container,
+    } = props;


Let's return immediate props destructuring

export const Gallery = ({ ... }: GalleryProps) => {

kseniya57 · 2026-07-10T10:49:57Z

+        container,
+    } = props;
+
+    const inlineRef = React.useRef<HTMLDivElement>(null);


Let's rename this to something like inlineGalleryContainerRef

kseniya57 · 2026-07-10T10:51:15Z

 - **Swipe Gestures**: Mobile swipe navigation (automatically disabled during zoom interaction)
 - **Fullscreen Mode**: Toggle fullscreen view
 - **Custom Actions**: Add custom action buttons for each gallery item
+- **Contained Mode**: Render the gallery inside its `container` bounds instead of over the whole viewport


Maybe Inline view will be clearer

Agree, done

kseniya57 · 2026-07-10T10:55:05Z

+    container?: undefined;
+};
+
+export type GalleryProps = GalleryModalProps | GalleryInlineProps;


Seems like this will be a braking change since only modal view properties could be used (as in the GalleryProvider) , there will be an error through the new union type

It's not a breaking change - existing modal usage keeps compiling:

GalleryModalProps keeps view?: 'modal' optional, so old call sites with no view (<Gallery open onOpenChange container>) still resolve to the modal branch.

GalleryInlineProps declares open?/onOpenChange?/container? as undefined rather than dropping them, so those keys still exist on both members - reads and keyof GalleryProps are unchanged, so property access / Pick / Omit all behave as before.

GalleryProvider is unaffected since it references Pick<GalleryModalProps, ...> directly, not the union.

The only thing the union newly forbids is combining view="inline" with open/onOpenChange/container - a new invalid combo that didn't exist before, so it can't break existing code.
Verified with npm run typecheck.

kseniya57 · 2026-07-10T12:50:47Z

    }

+    &_view_inline {
+        width: 100%;


Maybe this also should be controlled by the user

- add `view` prop ('modal' default | 'inline') to render the gallery in place instead of a modal - add controlled `activeItemIndex` / `onActiveItemIndexChange`, backed by a local `useConditionallyControlledState` - add `GalleryItem.id` to keep item previews reconciled by identity

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch from 6ceafa5 to cfe3760 Compare July 7, 2026 07:31

artemnikotin marked this pull request as ready for review July 7, 2026 07:34

artemnikotin requested a review from kseniya57 as a code owner July 7, 2026 07:34

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch from cfe3760 to 0e794b9 Compare July 8, 2026 11:27

artemnikotin requested review from ValeraS, amje and korvin89 as code owners July 8, 2026 11:27

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch from 0e794b9 to 5e50e2c Compare July 8, 2026 11:39

kseniya57 reviewed Jul 8, 2026

View reviewed changes

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch 2 times, most recently from ca3c517 to 9423eab Compare July 9, 2026 13:33

kseniya57 reviewed Jul 10, 2026

View reviewed changes

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch from 9423eab to 408497d Compare July 10, 2026 12:20

artemnikotin changed the title ~~feat(Gallery): add contained mode and controlled active item index~~ feat(Gallery): add inline view and controlled active item index Jul 10, 2026

kseniya57 approved these changes Jul 10, 2026

View reviewed changes

amje approved these changes Jul 13, 2026

View reviewed changes

artemnikotin force-pushed the feat/gallery-contained-and-controlled-index branch from 408497d to 1753e0b Compare July 13, 2026 12:23

kseniya57 merged commit 2a04394 into gravity-ui:main Jul 13, 2026
4 checks passed

gravity-ui-bot mentioned this pull request Jul 13, 2026

chore(main): release 4.23.0 #399

Merged


		export type GalleryProps = GalleryModalProps \| GalleryInlineProps;

		function resolveViewProps(props: GalleryProps) {

		@@ -0,0 +1,31 @@
		import * as React from 'react';

		// Copied from `@gravity-ui/uikit`'s private `useStateWithCallback` hook:


		import {useStateWithCallback} from '../useStateWithCallback';

		// Copied from `@gravity-ui/uikit`'s private `useConditionallyControlledState` hook:

Uh oh!

Conversation

artemnikotin commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gravity-ui-bot commented Jul 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

artemnikotin commented Jul 6, 2026 •

edited

Loading