# PageControl Guides
## Patterns
### Carousel Indicators
When to use:
- a short carousel or hero sequence needs compact navigation
Composition notes:
- keep the sequence short
- sync active state with the actual slide
Trade-offs:
- compact and familiar
- not informative enough for long sequences
```tsx
import { Card, Heading, PageControl, PageControlItem, Text } from '@vega-ui/react';
import { useId, useState } from 'react';
const slides = [
{ title: 'Plan your week', text: 'Drag tasks onto the calendar and see your free time at a glance.' },
{ title: 'Share with your team', text: 'Invite teammates to a board and assign tasks in one click.' },
{ title: 'Stay on track', text: 'Get a summary every Monday with what slipped and what is next.' },
];
export default function CarouselIndicators() {
const prefix = useId();
const [active, setActive] = useState(0);
const slide = slides[active];
return (
{slide.title}{slide.text}
{slides.map((item, index) => (
))}
);
}
```
### Timed Progress Dots
When to use:
- autoplay or timed advancement is part of the experience
Composition notes:
- use `PageControlProgress`
- keep duration aligned with the real autoplay timing
Trade-offs:
- communicates progression visually
- adds temporal complexity and potential accessibility risks
```tsx
import { Button, PageControl, PageControlItem, PageControlProgress, Text } from '@vega-ui/react';
import { useState } from 'react';
const stories = ['New arrivals', 'Autumn sale', 'Gift cards', 'Store opening'];
export default function TimedProgressIndicators() {
const [active, setActive] = useState(0);
const [paused, setPaused] = useState(false);
const advance = () => setActive((active + 1) % stories.length);
return (
);
}
```
### Step Indicators Above A Form
When to use:
- a multi-step flow needs lightweight progress cues
Composition notes:
- keep step semantics elsewhere if labels matter
- use `active` to reflect the real current step
Trade-offs:
- compact
- less explanatory than a labeled stepper
```tsx
import { Button, HelperText, Label, PageControl, PageControlItem, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, MouseEvent, useId, useState } from 'react';
const steps = ['Account', 'Workspace', 'Invite'];
export default function StepIndicatorAboveFormPages() {
const id = useId();
const [step, setStep] = useState(0);
const [reached, setReached] = useState(0);
const [result, setResult] = useState('');
const goTo = (index: number) => {
if (index > reached) return;
setStep(index);
};
const next = (event: MouseEvent) => {
const fieldset = event.currentTarget.form?.elements.namedItem(`step-${step}`);
if (!(fieldset instanceof HTMLFieldSetElement)) return;
const fields = Array.from(fieldset.elements) as HTMLInputElement[];
const valid = fields.every((field) => field.reportValidity());
if (!valid) return;
setStep(step + 1);
setReached(Math.max(reached, step + 1));
};
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setResult(`Workspace “${data.get('workspace')}” created for ${data.get('email')}.`);
};
return (
);
}
```
## Comparison
### Quick Decision Rule
Use `PageControl` for short sequences like onboarding steps or carousels. Use `Pagination` for real page navigation across result sets.
### `PageControl` vs `Pagination`
- Use `PageControl` for short, compact sequences.
- Use `Pagination` for explicit page numbers and dataset navigation.
### `PageControl` vs `Stepper`
- Use `PageControl` when indicators are intentionally minimal.
- Use a fuller stepper pattern when step labels and richer status matter.
### Choose This Component When
- the sequence is short
- compact indicators are enough
### Do Not Choose This Component When
- users need page numbers or routeable destinations
- each step requires visible labels and richer state
## Troubleshooting
### The Active Dot Does Not Match The Real Carousel Or Step
#### Symptom
The visible active indicator and the actual content state drift apart.
#### Likely Cause
The parent feature and `PageControl` are not sharing one source of truth.
#### How To Verify
- compare the current content index with the rendered `active` item
#### Fix
Drive both the content and `PageControl` from the same parent state.
### Progress Dots Animate But Nothing Advances
#### Symptom
The progress fill animates, but the content never changes.
#### Likely Cause
`PageControlProgress` was rendered without matching step-advance logic in the parent flow.
#### How To Verify
- inspect whether the parent updates active state on animation end or autoplay tick
#### Fix
Connect progress completion to the actual advancement logic or switch to static items.
### Long Sequences Feel Unreadable
#### Symptom
The row of indicators becomes hard to count or understand.
#### Likely Cause
`PageControl` is being used for too many items.
#### How To Verify
- count the visible items and compare with actual user comprehension
#### Fix
Switch to `Pagination`, a labeled stepper, or another richer navigation pattern.