Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(AspectRatio): add isCircle prop for circular containers (#2632)

Kenton Quatman254d52c1acad
diff --git a/apps/storybook/stories/AspectRatio.stories.tsx b/apps/storybook/stories/AspectRatio.stories.tsx
index a6260a72e3..ac3a6d63db 100644
--- a/apps/storybook/stories/AspectRatio.stories.tsx
+++ b/apps/storybook/stories/AspectRatio.stories.tsx
@@ -75,6 +75,12 @@ const meta: Meta<typeof XDSAspectRatio> = {
control: 'number',
description: 'The aspect ratio as width/height (e.g., 16/9 = 1.777...)',
},
+ shape: {
+ control: 'select',
+ options: ['rectangle', 'ellipse'],
+ description:
+ 'Container shape. Both respect the ratio; "ellipse" clips to an oval (circle at 1:1).',
+ },
},
};
@@ -171,6 +177,48 @@ export const Ultrawide21x9: Story = {
),
};
+export const EllipseCircle: Story = {
+ args: {
+ ratio: 1,
+ shape: 'ellipse',
+ },
+ render: args => (
+ <div {...stylex.props(styles.smallContainer)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ Ellipse at 1:1 — a circle (avatars, profile images)
+ </XDSText>
+ <XDSAspectRatio {...args}>
+ <img
+ {...stylex.props(styles.image)}
+ src={PLACEHOLDER_SQUARE}
+ alt="Circular media"
+ />
+ </XDSAspectRatio>
+ </div>
+ ),
+};
+
+export const EllipseOval: Story = {
+ args: {
+ ratio: 16 / 9,
+ shape: 'ellipse',
+ },
+ render: args => (
+ <div {...stylex.props(styles.container)}>
+ <XDSText type="supporting" xstyle={styles.sectionLabel}>
+ Ellipse at 16:9 — an oval (respects the ratio)
+ </XDSText>
+ <XDSAspectRatio {...args}>
+ <img
+ {...stylex.props(styles.image)}
+ src={PLACEHOLDER_IMAGE}
+ alt="Oval media"
+ />
+ </XDSAspectRatio>
+ </div>
+ ),
+};
+
export const WithPlaceholderSkeleton: Story = {
render: () => (
<div {...stylex.props(styles.storyWrapper)}>
diff --git a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjs b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjs
new file mode 100644
index 0000000000..7e5aec73b1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.doc.mjs
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'AspectRatio',
+ name: 'AspectRatio — Circle Image',
+ displayName: 'AspectRatio — Circle Image',
+ description: 'Circular container via shape="ellipse" with ratio={1}, ideal for avatars and profile images.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['AspectRatio', 'Center'],
+};
diff --git a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx
new file mode 100644
index 0000000000..5337ed276d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioCircleImage.tsx
@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSCenter} from '@xds/core/Center';
+
+export default function AspectRatioCircleImage() {
+ return (
+ <XDSCenter width={300}>
+ <XDSAspectRatio ratio={1} shape="ellipse">
+ <img
+ src="https://lookaside.facebook.com/assets/xds_oss/light-home-square-1.png"
+ alt="Circular image"
+ style={{
+ width: '100%',
+ height: '100%',
+ objectFit: 'cover',
+ }}
+ />
+ </XDSAspectRatio>
+ </XDSCenter>
+ );
+}
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
index b1efe62e48..6bc2c22c5e 100644
--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -13,6 +13,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+ {guidance: true, description: 'Use `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},
{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},
{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},
],
@@ -24,6 +25,12 @@ export const docs = {
description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
required: true,
},
+ {
+ name: 'shape',
+ type: "'rectangle' | 'ellipse'",
+ description: 'Container shape. Both respect the `ratio`. `ellipse` clips to an oval (a circle when `ratio={1}`).',
+ default: "'rectangle'",
+ },
{
name: 'children',
type: 'ReactNode',
@@ -40,12 +47,29 @@ export const docs = {
playground: {
defaults: {
ratio: 16 / 9,
- children: {__element: 'XDSCenter', props: {height: '100%'}, children: {__element: 'XDSText', props: {color: 'secondary'}, children: '16:9'}},
+ shape: 'rectangle',
+ // Fixed height + auto width lets the CSS `aspect-ratio` drive the box
+ // width as the ratio knob changes (the component's base width is 100%,
+ // which is why the preview was full-width regardless of the ratio).
+ style: {
+ height: 300,
+ width: 'auto',
+ backgroundColor: 'var(--color-background-blue)',
+ },
+ children: {
+ __element: 'XDSCenter',
+ props: {height: '100%'},
+ children: {
+ __element: 'XDSText',
+ props: {color: 'primary'},
+ children: 'Aspect Ratio',
+ },
+ },
},
},
theming: {
targets: [
- {className: 'xds-aspect-ratio'},
+ {className: 'xds-aspect-ratio', visualProps: ['shape']},
],
},
};
@@ -60,12 +84,14 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+ {guidance: true, description: 'Use `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},
{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},
{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},
],
},
props: [
{name: 'ratio', type: 'number', description: '宽高比,以宽/高表示(例如 16/9、1)。', required: true},
+ {name: 'shape', type: "'rectangle' | 'ellipse'", description: '容器形状,二者均遵循 `ratio`。`ellipse` 裁剪为椭圆(当 `ratio={1}` 时为圆形)。', default: "'rectangle'"},
{name: 'children', type: 'ReactNode', description: '通过绝对定位填充容器的内容。', required: true},
{
name: 'xstyle',
@@ -76,7 +102,7 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'xds-aspect-ratio'},
+ {className: 'xds-aspect-ratio', visualProps: ['shape']},
],
},
};
@@ -90,12 +116,14 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
{guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+ {guidance: true, description: 'Use `shape="ellipse"` for circular/oval media like avatars; combine with `ratio={1}` for a perfect circle.'},
{guidance: false, description: 'Use for general layout containers — use standard layout components instead.'},
{guidance: false, description: 'Nest AspectRatio containers — one level is sufficient.'},
],
},
propDescriptions: {
ratio: 'width/height ratio (e.g. 16/9, 1)',
+ shape: "container shape: 'rectangle' (default) or 'ellipse'; both respect ratio",
children: 'content positioned absolutely to fill container',
xstyle: 'StyleX layout customization via stylex.create()',
},
diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx
index 3574fc567b..6c6a905aa4 100644
--- a/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx
+++ b/packages/core/src/AspectRatio/XDSAspectRatio.test.tsx
@@ -82,6 +82,42 @@ describe('XDSAspectRatio', () => {
expect(element.style.aspectRatio).toBe(String(ratio));
});
+ it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
+ render(
+ <XDSAspectRatio ratio={1} shape="ellipse" data-testid="aspect-ratio">
+ <div>Circle</div>
+ </XDSAspectRatio>,
+ );
+ const element = screen.getByTestId('aspect-ratio');
+ expect(element.style.aspectRatio).toBe('1');
+ expect(element.className).toContain('ellipse');
+ });
+
+ it('ellipse respects a non-square ratio (oval)', () => {
+ render(
+ <XDSAspectRatio ratio={16 / 9} shape="ellipse" data-testid="aspect-ratio">
+ <div>Oval</div>
+ </XDSAspectRatio>,
+ );
+ const element = screen.getByTestId('aspect-ratio');
+ // Ratio is preserved — the ellipse does not force 1:1.
+ expect(element.style.aspectRatio).toBe(String(16 / 9));
+ expect(element.className).toContain('ellipse');
+ });
+
+ it('defaults to the rectangle shape', () => {
+ render(
+ <XDSAspectRatio ratio={1} data-testid="aspect-ratio">
+ <div>Rectangle by default</div>
+ </XDSAspectRatio>,
+ );
+ const element = screen.getByTestId('aspect-ratio');
+ expect(element.style.aspectRatio).toBe('1');
+ expect(element.className).toContain('rectangle');
+ // No ellipse border-radius when shape is the default rectangle
+ expect(element.style.borderRadius).toBe('');
+ });
+
it('forwards ref correctly', () => {
const ref = vi.fn();
render(
diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
index aafd8f1fcd..3d88ab0031 100644
--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx
+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
@@ -20,6 +20,14 @@ import * as stylex from '@stylexjs/stylex';
import type {XDSBaseProps} from '../XDSBaseProps';
import {xdsClassName, mergeProps} from '../utils';
+/**
+ * The shape of the aspect ratio container.
+ * - `rectangle`: standard rectangular container (default).
+ * - `ellipse`: clips the container to an ellipse. Combined with the `ratio`,
+ * this renders a circle at `ratio={1}` and an oval at non-square ratios.
+ */
+export type XDSAspectRatioShape = 'rectangle' | 'ellipse';
+
export interface XDSAspectRatioProps extends XDSBaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLDivElement>;
@@ -28,6 +36,24 @@ export interface XDSAspectRatioProps extends XDSBaseProps<HTMLDivElement> {
*/
ratio: number;
+ /**
+ * The shape of the container. Both shapes respect the provided `ratio`.
+ * - `rectangle` (default): a standard rectangular container.
+ * - `ellipse`: clips the container to an ellipse — a circle when `ratio={1}`,
+ * or an oval at other ratios. Pair with a child that fills the container
+ * (e.g. an image with `objectFit: 'cover'`).
+ *
+ * @default 'rectangle'
+ *
+ * @example
+ * ```
+ * <XDSAspectRatio ratio={1} shape="ellipse">
+ * <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+ * </XDSAspectRatio>
+ * ```
+ */
+ shape?: XDSAspectRatioShape;
+
/**
* Content to render inside the aspect ratio container.
* The child element will be positioned absolutely to fill the container.
@@ -43,6 +69,11 @@ const styles = stylex.create({
minHeight: 0,
flexShrink: 0,
},
+ ellipse: {
+ // 50% on both axes follows the box dimensions, so the clip respects the
+ // ratio: a circle at 1:1 and an oval at non-square ratios.
+ borderRadius: '50%',
+ },
child: {
position: 'absolute',
top: 0,
@@ -59,15 +90,27 @@ const styles = stylex.create({
* is positioned absolutely to fill the container, which is useful for images,
* videos, embeds, and placeholders.
*
+ * Use `shape="ellipse"` to clip the container into an ellipse — a circle at
+ * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
+ * `ratio`.
+ *
* @example
* ```
* <XDSAspectRatio ratio={16 / 9}>
* <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />
* </XDSAspectRatio>
* ```
+ *
+ * @example
+ * ```
+ * <XDSAspectRatio ratio={1} shape="ellipse">
+ * <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+ * </XDSAspectRatio>
+ * ```
*/
export function XDSAspectRatio({
ratio,
+ shape = 'rectangle',
children,
xstyle,
className,
@@ -79,8 +122,12 @@ export function XDSAspectRatio({
<div
ref={ref}
{...mergeProps(
- xdsClassName('aspect-ratio'),
- stylex.props(styles.container, xstyle),
+ xdsClassName('aspect-ratio', {shape}),
+ stylex.props(
+ styles.container,
+ shape === 'ellipse' && styles.ellipse,
+ xstyle,
+ ),
className,
{...style, aspectRatio: ratio},
)}
diff --git a/packages/core/src/AspectRatio/index.ts b/packages/core/src/AspectRatio/index.ts
index ed0303d9a4..a273fc96e7 100644
--- a/packages/core/src/AspectRatio/index.ts
+++ b/packages/core/src/AspectRatio/index.ts
@@ -12,4 +12,4 @@
*/
export {XDSAspectRatio} from './XDSAspectRatio';
-export type {XDSAspectRatioProps} from './XDSAspectRatio';
+export type {XDSAspectRatioProps, XDSAspectRatioShape} from './XDSAspectRatio';