N Grid

Naive UI Grid Component

Based on CSS Grid. Responsive. Keep away from IE.

When to Use

Use this component when:

• Grid layouts: Create multi-column layouts
• Responsive designs: Build responsive grid systems
• Dashboard layouts: Arrange content in grid patterns
• Form layouts: Create multi-column form layouts

When to Invoke

Invoke this skill when:

• User needs to implement a responsive grid layout
• User wants to create multi-column designs
• User needs collapsible grid items
• User wants responsive breakpoints
• User asks about grid item spanning or offsetting

Features

• CSS Grid Based: Uses modern CSS Grid layout
• Responsive: Self-responsive or screen-responsive modes
• Item Responsive: Individual grid items can be responsive
• Collapsible: Support for collapsed rows with overflow detection
• Gap Control: Horizontal and vertical gap support
• Span & Offset: Control column spanning and offsetting
• Suffix Support: Special suffix slot for overflow content

API Reference

Grid Props

GridItem Props

Grid Slots

GridItem Slots

Basic Usage

Basic Grid

n-grid-item has an alias called n-gi.

<template>
  <n-grid x-gap="12" :cols="4">
    <n-gi>
      <div class="light-green" />
    </n-gi>
    <n-gi>
      <div class="green" />
    </n-gi>
    <n-gi>
      <div class="light-green" />
    </n-gi>
    <n-gi>
      <div class="green" />
    </n-gi>
  </n-grid>
</template>

<style scoped>
.light-green {
  height: 108px;
  background-color: rgba(0, 128, 0, 0.12);
}
.green {
  height: 108px;
  background-color: rgba(0, 128, 0, 0.24);
}
</style>

Gap

<template>
  <n-grid :x-gap="12" :y-gap="8" :cols="4">
    <n-grid-item>
      <div class="light-green" />
    </n-grid-item>
    <n-grid-item>
      <div class="green" />
    </n-grid-item>
    <n-grid-item>
      <div class="light-green" />
    </n-grid-item>
    <n-grid-item>
      <div class="green" />
    </n-grid-item>
  </n-grid>
</template>

Offset

<template>
  <n-grid :x-gap="12" :cols="4">
    <n-grid-item :offset="1">
      <div class="light-green" />
    </n-grid-item>
    <n-grid-item :offset="1">
      <div class="green" />
    </n-grid-item>
  </n-grid>
</template>

Common Patterns

Responsive Columns

<template>
  <n-divider>Self Responsive</n-divider>
  <n-grid cols="2 400:4 600:6">
    <n-grid-item>
      <div class="light-green">1</div>
    </n-grid-item>
    <n-grid-item>
      <div class="green">2</div>
    </n-grid-item>
    <n-grid-item>
      <div class="light-green">3</div>
    </n-grid-item>
    <n-grid-item>
      <div class="green">4</div>
    </n-grid-item>
  </n-grid>
  
  <n-divider>Screen Responsive</n-divider>
  <n-grid cols="2 s:3 m:4 l:5 xl:6 2xl:7" responsive="screen">
    <n-grid-item>
      <div class="light-green">1</div>
    </n-grid-item>
    <n-grid-item>
      <div class="green">2</div>
    </n-grid-item>
  </n-grid>
</template>

Responsive Grid Item

<template>
  <n-grid cols="4" item-responsive>
    <n-grid-item span="0 400:1 600:2 800:3">
      <div class="light-green">
        0 ~ 400px: hidden<br>
        400 ~ 600px: span 1<br>
        600 ~ 800px: span 2<br>
        800px +: span 3
      </div>
    </n-grid-item>
    <n-grid-item>
      <div class="green">2</div>
    </n-grid-item>
  </n-grid>
</template>

Collapse with Suffix

<template>
  <n-grid :cols="5" :collapsed="gridCollapsed" :collapsed-rows="gridCollapsedRows">
    <n-gi v-for="i in gridItemCount" :key="i" :class="i % 2 ? 'green' : 'light-green'">
      {{ i }}
    </n-gi>
    <n-gi v-if="showSuffix" suffix class="suffix" #="{ overflow }">
      {{ overflow ? 'Node Overflows Exists' : 'No Node Overflows' }}
    </n-gi>
  </n-grid>
</template>

Avoid SSR Layout Shift

<template>
  <n-grid :x-gap="12" :y-gap="12" :cols="4" layout-shift-disabled>
    <n-gi>
      <div class="light-green" />
    </n-gi>
    <n-gi :span="2">
      <div class="green" />
    </n-gi>
    <n-gi>
      <div class="light-green" />
    </n-gi>
  </n-grid>
</template>

Span Multiple Columns

<template>
  <n-grid :cols="4" :x-gap="12">
    <n-gi :span="2">
      <div class="green">Span 2</div>
    </n-gi>
    <n-gi>
      <div class="light-green">Span 1</div>
    </n-gi>
    <n-gi>
      <div class="light-green">Span 1</div>
    </n-gi>
  </n-grid>
</template>

Best Practices

1. Use n-grid over n-legacy-grid: Prefer the CSS Grid-based component for modern browsers

2. Encapsulation warning: n-grid-item can't be encapsulated in another component

3. SSR considerations: Use layout-shift-disabled to avoid SSR layout shift if you don't need responsive functionality

4. Responsive breakpoints: Customize breakpoints in n-config-provider

5. Hidden items: Set span to 0 to hide grid items

6. Suffix slot: Use suffix slot for "show more" or overflow indicators