Understanding Pine Script's plotshape() Function: A Comprehensive Guide

When working with TradingView's Pine Script, the plotshape() function is a powerful tool to visually highlight key trading signals on your charts. It allows traders and developers to plot various shapes-like arrows, crosses, diamonds, and triangles-directly on price bars based on specific conditions, making charts more intuitive and actionable.

What is plotshape() in Pine Script?

plotshape() is a built-in Pine Script function used to display predefined shapes on a chart at bars where certain logical conditions are met. For example, you can mark buy signals, sell signals, or crossover points with distinct shapes that stand out visually.

Key Parameters of plotshape()

• series: A boolean condition that determines when to plot the shape. Shapes appear only on bars where this condition is true.
• title: The name of the shape series shown in the indicator's settings.
• location: Position of the shape relative to the bar (e.g., location.abovebar or location.belowbar).
• color: Color of the shape, which can be static or dynamically set based on conditions.
• style: The shape type, such as shape.triangleup, shape.xcross, shape.diamond, and more.
• size: Controls the size of the shape (size.small, size.normal, size.large).
• offset: Shifts the shape left or right relative to the bar.
• text and textcolor: Optional parameters to add non-dynamic text alongside shapes.

Why Use plotshape()?

• Visual Clarity: Highlights important trading signals like moving average crossovers or price breakouts.
• Customization: Choose from multiple shapes and colors to differentiate between signal types.
• Ease of Use: Simple syntax that integrates well with other Pine Script functions and conditional logic.

Example: Plotting Buy Signals on Moving Average Crossovers

Here's a basic example that plots a green triangle above bars where a fast moving average crosses above a slow moving average, signaling a potential buy opportunity:

//@version=5
indicator("MA Crossover Signals", overlay=true)

fastMA = ta.sma(close, 9)
slowMA = ta.sma(close, 21)
bullishSignal = ta.crossover(fastMA, slowMA)

plotshape(bullishSignal, title="Buy Signal", location=location.abovebar, color=color.green, style=shape.triangleup, size=size.small)

This script calculates two simple moving averages and uses plotshape() to mark bullish crossovers with a green triangle above the bar.

Tips for Effective Use of plotshape()

• Combine plotshape() with logical operators (and, or) to create complex conditions.
• Use the color parameter dynamically to change shape colors based on market conditions.
• Adjust the offset to fine-tune the shape's position relative to bars.
• Remember that the text parameter requires constant strings, so dynamic values must be handled with labels or tables if needed.

Common Shapes Available in plotshape()

Shape Argument	Description
shape.xcross	Cross shape
shape.arrowup	Upward arrow
shape.arrowdown	Downward arrow
shape.circle	Circle
shape.square	Square
shape.triangleup	Triangle pointing up
shape.triangledown	Triangle pointing down
shape.diamond	Diamond
shape.flag	Flag
shape.labelup	Label above bar
shape.labeldown	Label below bar

These shapes help visually categorize different signals or events on your chart.