feat: global labelPlacement prop

[macci001]

Closes #4621

📝 Description

Adds the support for the labelPlacement prop in NextUI provider.

🚀 New behavior

• Following components have been tested:
  • input
  • textarea
  • select
  • auto-complete
  • date-picker
  • date-range-picker
  • time-input

💣 Is this a breaking change (Yes/No): No

Summary by CodeRabbit

Release Notes

• New Features

  • Added global labelPlacement property for consistent label positioning across components.
  • Introduced useLabelPlacement hook for flexible label positioning.
  • Enhanced Storybook configuration to support label placement customization.

• Improvements

  • Streamlined label placement logic in date input, time input, date picker, select, and input components.
  • Updated default label placement for select component from "inside" to "outside".

• Breaking Changes

  • Removed default "inside" label placement for some components.
  • Updated peer dependency versions for system and theme packages.

[linear]

ENG-1694 [Feature] Add `labelPlacement` to `NextUIProvider`

[changeset-bot]

🦋 Changeset detected

Latest commit: 8523a5f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 28 packages

Name	Type
@heroui/date-picker	Patch
@heroui/date-input	Patch
@heroui/select	Patch
@heroui/input	Patch
@heroui/system	Patch
@heroui/theme	Patch
@heroui/react	Patch
@heroui/accordion	Patch
@heroui/autocomplete	Patch
@heroui/drawer	Patch
@heroui/modal	Patch
@heroui/navbar	Patch
@heroui/popover	Patch
@heroui/tabs	Patch
@heroui/calendar	Patch
@heroui/checkbox	Patch
@heroui/dropdown	Patch
@heroui/form	Patch
@heroui/input-otp	Patch
@heroui/listbox	Patch
@heroui/menu	Patch
@heroui/radio	Patch
@heroui/slider	Patch
@heroui/snippet	Patch
@heroui/table	Patch
@heroui/tooltip	Patch
@heroui/aria-utils	Patch
@heroui/framer-utils	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
heroui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 30, 2025 11:12am
heroui-sb	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 30, 2025 11:12am
nextui-docs-v2	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 30, 2025 11:12am
nextui-storybook-v2	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 30, 2025 11:12am

[coderabbitai]

Walkthrough

The pull request introduces a global labelPlacement property across multiple components in the @heroui library. This enhancement allows developers to consistently define label positioning through a centralized configuration. The changes span components like date-picker, date-input, select, input, system, and theme, implementing a new useLabelPlacement hook to manage label placement dynamically. The modification provides more flexible UI layout options and simplifies label positioning across different components.

Changes

File Path	Change Summary
packages/core/system/src/provider-context.ts	Added optional labelPlacement property to ProviderContextProps
packages/core/system/src/provider.tsx	Integrated labelPlacement into NextUIProviderProps and context
packages/core/system/src/hooks/use-label-placement.ts	Created new hook for managing label placement logic
Multiple theme component files	Removed default labelPlacement: "inside" from various components
Multiple component use-* files	Updated label placement determination using new useLabelPlacement hook
Multiple package.json files	Updated peer dependency versions for system and theme packages

Assessment against linked issues

Objective	Addressed	Explanation
Global theme setting for label placement	✅
Ability to set default label placement	✅
Reduce need to override label placement for individual components	✅

---

📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ae78d81 and 8523a5f.

📒 Files selected for processing (1)

• packages/components/input/src/use-input.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/components/input/src/use-input.ts

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: TypeScript
• GitHub Check: Build

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 1

🧹 Outside diff range and nitpick comments (5)

.changeset/chilly-dancers-switch.md (1)

9-10: Enhance the changeset description

The current description could be more informative. Consider adding:

• Available values for labelPlacement (inside, outside, outside-left)
• Impact on affected components
• Migration notes if any

Also, add a space between "prop" and the ticket reference.

Here's a suggested improvement:

-Adding support for global labelPlacement prop.(ENG-1694)
+Adding support for global labelPlacement prop to customize label positioning across components. 
+
+The labelPlacement prop can be set globally via NextUIProvider with the following values:
+- inside
+- outside
+- outside-left
+
+Affects: Input, Select, DatePicker, DateInput, and related components.
+
+(ENG-1694)

🧰 Tools

🪛 LanguageTool

[uncategorized] ~10-~10: Possible missing comma found.
Context: ...": patch --- Adding support for global labelPlacement prop.(ENG-1694)

(AI_HYDRA_LEO_MISSING_COMMA)

packages/core/system/src/provider-context.ts (1)

14-19: Enhance JSDoc documentation for labelPlacement

While the documentation is present, it would be more helpful to include:

• Description of each possible value
• Example usage
• Default behavior implications

Consider expanding the documentation like this:

  /**
   * Position where the label should appear.
   *
+  * @description
+  * - "inside": Label appears within the input field
+  * - "outside": Label appears above the input field
+  * - "outside-left": Label appears to the left of the input field
+  * 
+  * @example
+  * ```tsx
+  * <NextUIProvider labelPlacement="outside">
+  *   <Input label="Username" />
+  * </NextUIProvider>
+  * ```
   *
   * @default undefined
   */

apps/docs/content/docs/api-references/nextui-provider.mdx (1)

145-150: Enhance the documentation for the labelPlacement prop.

The documentation could be more detailed to help developers understand the impact of each value:

 `labelPlacement`
 
-  - **Description**: Determines the position where label should appear, such as inside, outside or outside-left of the component.
+  - **Description**: Determines the position where label should appear in form components:
+    - `inside`: Places the label inside the input field, floating when focused or filled
+    - `outside`: Places the label above the input field
+    - `outside-left`: Places the label to the left of the input field
+    - `undefined`: Uses the default placement for each component
-  - **Type**: `string` | `undefined`
-  - **Possible Values**: `inside` | `outside` | `outside-left` | `undefined`
+  - **Type**: `"inside" | "outside" | "outside-left" | undefined`
   - **Default**: `undefined`

packages/components/date-input/src/use-time-input.ts (1)

137-145: Optimize the useMemo dependency array.

Consider destructuring the required properties earlier to make the dependencies more explicit and maintainable.

+  const globalLabelPlacement = globalContext?.labelPlacement;
+
   const labelPlacement = useMemo<DateInputVariantProps["labelPlacement"]>(() => {
     const labelPlacement =
-      originalProps.labelPlacement ?? globalContext?.labelPlacement ?? "inside";
+      originalProps.labelPlacement ?? globalLabelPlacement ?? "inside";
 
     if (labelPlacement === "inside" && !label) {
       return "outside";
     }
 
     return labelPlacement;
-  }, [originalProps.labelPlacement, globalContext?.labelPlacement, label]);
+  }, [originalProps.labelPlacement, globalLabelPlacement, label]);

packages/components/date-picker/src/use-date-picker-base.ts (1)

12-12: Consider importing from a shared location.

The useMemo import could be grouped with other React hooks if they're imported from the same location.

-import {useCallback, useMemo} from "react";
+import {useCallback, useMemo, type ReactNode} from "react";

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 77206bc and 5fffcdd.

📒 Files selected for processing (14)

• .changeset/chilly-dancers-switch.md (1 hunks)
• apps/docs/content/docs/api-references/nextui-provider.mdx (1 hunks)
• packages/components/date-input/src/use-date-input.ts (1 hunks)
• packages/components/date-input/src/use-time-input.ts (1 hunks)
• packages/components/date-picker/src/use-date-picker-base.ts (2 hunks)
• packages/components/date-picker/src/use-date-range-picker.ts (4 hunks)
• packages/components/input/src/use-input.ts (2 hunks)
• packages/components/select/src/use-select.ts (1 hunks)
• packages/core/system/src/provider-context.ts (1 hunks)
• packages/core/system/src/provider.tsx (3 hunks)
• packages/core/theme/src/components/date-input.ts (0 hunks)
• packages/core/theme/src/components/input.ts (0 hunks)
• packages/core/theme/src/components/select.ts (0 hunks)
• packages/storybook/.storybook/preview.tsx (2 hunks)

💤 Files with no reviewable changes (3)

• packages/core/theme/src/components/date-input.ts
• packages/core/theme/src/components/input.ts
• packages/core/theme/src/components/select.ts

🧰 Additional context used

🪛 LanguageTool

.changeset/chilly-dancers-switch.md

[uncategorized] ~10-~10: Possible missing comma found.
Context: ...": patch --- Adding support for global labelPlacement prop.(ENG-1694)

(AI_HYDRA_LEO_MISSING_COMMA)

🔇 Additional comments (11)

.changeset/chilly-dancers-switch.md (1)

1-8: LGTM: Version bumps are appropriate

The patch version bumps are correctly specified for all affected components, which aligns with the non-breaking nature of the changes.

packages/storybook/.storybook/preview.tsx (2)

10-10: LGTM: Proper integration of labelPlacement in Storybook decorator

The labelPlacement property is correctly destructured from globals and properly passed to the NextUIProvider.

Also applies to: 16-16

---

130-141: LGTM: Well-structured Storybook toolbar configuration

The labelPlacement toolbar configuration is well-implemented with clear title, description, and appropriate options matching the provider's supported values.

packages/core/system/src/provider.tsx (1)

61-61: LGTM: Clean implementation of labelPlacement in provider

The labelPlacement property is properly:

• Destructured from props
• Included in the memoized context
• Added to the dependency array

Also applies to: 89-89, 98-98

packages/components/date-input/src/use-date-input.ts (1)

195-203: LGTM: Clean implementation of labelPlacement logic

The implementation correctly handles the label placement hierarchy:

1. Uses prop value if provided
2. Falls back to global context value
3. Defaults to "inside"
4. Automatically switches to "outside" when no label is present

packages/components/input/src/use-input.ts (2)

234-242: LGTM: Proper handling of file input edge case

The code correctly handles the special case for file inputs by defaulting to "outside" placement and providing a clear warning when the global context attempts to use "inside" placement.

---

253-261: LGTM: Consistent implementation of labelPlacement logic

The implementation aligns with the standard pattern used across components:

1. Props take precedence
2. Falls back to global context
3. Uses "inside" as default
4. Automatically switches to "outside" when no label is present

packages/components/select/src/use-select.ts (1)

347-355: LGTM: Consistent implementation of labelPlacement logic

The implementation maintains consistency with other components by following the same pattern:

1. Props take precedence
2. Falls back to global context
3. Uses "inside" as default
4. Automatically switches to "outside" when no label is present

packages/components/date-picker/src/use-date-range-picker.ts (3)

63-63: LGTM: Label parameter addition is well-integrated

The addition of the label parameter to the hook's props is consistent with the PR's objective and maintains backward compatibility.

---

399-399: LGTM: Proper label prop handling

The label prop is correctly forwarded to the input group and exposed in the hook's return value, following React best practices.

Also applies to: 427-427

---

148-156: Verify the automatic label placement behavior

The logic forces outside placement when there's no label, even if inside was explicitly specified. This automatic override might:

1. Cause unexpected behavior for consumers
2. Lead to layout shifts if the label changes dynamically
3. Conflict with explicit placement preferences

Consider:

• Documenting this behavior
• Making it configurable
• Respecting the explicit placement preference

✅ Verification successful

The automatic label placement behavior is consistent across components

The behavior of forcing outside placement when there's no label is a deliberate design pattern implemented consistently across multiple form components:

• Input component (use-input.ts)
• Select component (use-select.ts)
• Date/Time inputs (use-date-input.ts, use-time-input.ts)
• Date pickers (use-date-picker-base.ts, use-date-range-picker.ts)

This consistent implementation suggests it's an intentional UX decision to prevent empty inside labels that could cause layout issues or poor user experience. The behavior is also handled uniformly through the NextUI Provider's global context.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for similar behavior in other components
ast-grep --pattern 'if ($placement === "inside" && !$label) {
  return "outside";
}'

Length of output: 86

---

Script:

#!/bin/bash
# Search for similar behavior with labelPlacement in other components
rg -A 3 'labelPlacement.*=.*"inside"' --type ts

# Search for any label placement logic
rg -A 3 'labelPlacement' --type ts

# Search for documentation about label placement
fd README.md | xargs rg -i 'label.*placement|placement.*label'

Length of output: 67972

[coderabbitai]

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (1)

packages/core/system/src/hooks/use-label-placement.ts (1)

12-20: Consider adding JSDoc documentation.

The implementation logic is solid with proper fallback handling and edge cases. However, adding JSDoc documentation would help explain the behavior, especially the special case where "inside" placement defaults to "outside" when no label is provided.

+/**
+ * Custom hook to determine label placement based on props and global context.
+ * @param props.labelPlacement - Optional label placement override
+ * @param props.label - Optional label content
+ * @returns The computed label placement, defaulting to "outside" if placement is "inside" with no label
+ */
 export function useLabelPlacement(props: {

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5fffcdd and db5d31c.

📒 Files selected for processing (8)

• packages/components/date-input/src/use-date-input.ts (2 hunks)
• packages/components/date-input/src/use-time-input.ts (2 hunks)
• packages/components/date-picker/src/use-date-picker-base.ts (2 hunks)
• packages/components/date-picker/src/use-date-range-picker.ts (5 hunks)
• packages/components/select/src/use-select.ts (2 hunks)
• packages/core/system/src/hooks/index.ts (1 hunks)
• packages/core/system/src/hooks/use-label-placement.ts (1 hunks)
• packages/core/system/src/index.ts (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• packages/core/system/src/hooks/index.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• packages/components/date-input/src/use-time-input.ts
• packages/components/date-picker/src/use-date-picker-base.ts
• packages/components/select/src/use-select.ts
• packages/components/date-input/src/use-date-input.ts
• packages/components/date-picker/src/use-date-range-picker.ts

🔇 Additional comments (3)

packages/core/system/src/hooks/use-label-placement.ts (2)

5-8: LGTM! Well-defined props interface.

The props interface is clear and type-safe, using proper TypeScript types for labelPlacement and label.

---

9-10: Verify error handling for missing provider context.

The hook accesses globalContext without null checks. While the optional chaining on line 10 prevents runtime errors, we should verify this behavior is intentional.

packages/core/system/src/index.ts (1)

36-37: LGTM! Clean export addition.

The useLabelPlacement hook export follows the established pattern and maintains consistency with other exports.

[wingkwong]

please resolve conflicts

[wingkwong]

• synced with canary
• updated peerDepenedency

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.changeset/chilly-dancers-switch.md (1)

10-10: Enhance the changeset description.

Consider adding more details about:

• The purpose and benefits of the global labelPlacement prop
• The components affected by this change
• Any migration steps or usage examples

Also, add a comma after "prop" for better readability.

-Adding support for global labelPlacement prop. (ENG-1694)
+Adding support for global labelPlacement prop, enabling consistent label positioning across date-picker, date-input, select, input, and other components. (ENG-1694)

🧰 Tools

🪛 LanguageTool

[uncategorized] ~10-~10: Possible missing comma found.
Context: ...": patch --- Adding support for global labelPlacement prop. (ENG-1694)

(AI_HYDRA_LEO_MISSING_COMMA)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 03e9405 and ae78d81.

📒 Files selected for processing (1)

• .changeset/chilly-dancers-switch.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

.changeset/chilly-dancers-switch.md

[uncategorized] ~10-~10: Possible missing comma found.
Context: ...": patch --- Adding support for global labelPlacement prop. (ENG-1694)

(AI_HYDRA_LEO_MISSING_COMMA)

⏰ Context from checks skipped due to timeout of 90000ms (1)

• GitHub Check: Build

🔇 Additional comments (1)

.changeset/chilly-dancers-switch.md (1)

1-8: LGTM! Patch version bumps are appropriate.

The patch version updates align with the non-breaking nature of adding the global labelPlacement prop support across these components.

[jprosevear]

Works great in canary. Saves a whole bunch of abstraction for me.